Printer

The _printer is designed to help print data on screen quickly and easily. Just create a new _printer object and start printing with the print() method. There are also many convenient methods to easily customize and style the _printer.

Please make sure to import the Printer library in your script, before following along with the examples.

Always create a printer under the barstate.islast condition.

Do not use var when assigning a printer to a variable.

Creating a printer object

// First import the library and give it a namespace.
// import faiyaz7283/printer/<latest-version> as p

// Always create printer under the `barstate.islast` condition. 
if barstate.islast

  // Do not assign with `var`. 
  // Use the recommended printer() function to initialize the printer object.
  printer = p.printer()

Below we will go through all the available methods and some examples of how to use them. All the examples below assumes we already have a printer object created.

It is recommended to use methods instead of directly interacting with the printer properties. Direct interaction with certain properties will cause unintended behavior.

printer()

printer(): Create a new printer object.

// For quick initialization, just call the printer method. It will use all default values.
printer = p.printer()

// To customize the printer with all available options.
printer = printer(
  header = 'A header string for display.',
  footer = 'A footer string for display.',
  stack = true,
  loc = position.top_right,
  tableStyle = tableStyle.new(frameColor = color.white, frameWidth = 1),
  headerStyle = headerStyle.new(textSize = size.large),
  footerStyle = footerStyle.new(textHalign = text.align_right, textSize = size.small),
  titleStyle = titleStyle.new(top = false, textHalign = text.align_center),
  keyCellStyle = cellStyle.new(),
  cellStyle = cellStyle.new(textHalign = text.align_right),
  gutterStyle = gutterStyle.new(gutter = true),
  theme = 'purple',
  debug = false)

cell()

  • cell(): Used for changing the orientation of arrays to horizontal.
  • cell(): Used for setting a custom cellStyle.
  • The last example assumes we already have a variable called customCellStyle.
// For printing arrays vertically, set horizontal to false (default).
printer.cell(horizontal=false) 

// For printing arrays horizontally, set horizontal to true.
printer.cell(horizontal=true) 

// Set a cellStyle.
printer.cell(cellStyle=customCellStyle)

debug()

debug(): When set to true, adds helpful debugging information to the tooltip.

// Turn on debugger.
printer.debug(true) 

// Turn off debugger (default).
printer.debug(false)

footer(): Used to set a footer text and footerStyle. The example assumes we already have a variable called customFooterStyle.

// Set footer text and style.
printer.footer("Some footer", footerStyle=customFooterStyle)

gutter()

  • gutter(): Used for adding a gutter space between each print() statements.
  • gutter(): Used for setting a custom gutterStyle.
  • The last example assumes we already have a variable called customGutterStyle.
// Set gutter on (default).
printer.gutter(true) 

// Set gutter off.
printer.gutter(false) 

// Set a gutterStyle.
printer.gutter(gutterStyle=customGutterStyle)

header(): Used for setting a header text and headerStyle. The example assumes we already have a variable called customHeaderStyle.

// Set header text and style.
printer.header("Some header", headerStyle=customHeaderStyle)

print()

print(): Outputs data onto the screen. Some of the examples below assumes we already have the variables called customTitleStyle and customCellStyle.

// Printing: Basic types.

// string
str  = tools._rndmString()
printer.print(str)

// float
flt  = tools._rndmFloat()
printer.print(flt)

// int
int  = tools._rndmInt()
printer.print(int)

// bool
bool = tools._rndmBool()
printer.print(bool)

// color
clr  = tools._rndmColor()
printer.print(clr)

//-----------------------------------

// Printing: Arrays.

// array<string>
strArr  = tools._rndmStringArray()
printer.print(strArr)

// array<float>
fltArr  = tools._rndmFloatArray()
printer.print(fltArr)

// array<int>
intArr  = tools._rndmIntArray()
printer.print(intArr)

// array<bool>
boolArr = tools._rndmBoolArray()
printer.print(boolArr)

// array<color>
clrArr  = tools._rndmColorArray()
printer.print(clrArr)

//-----------------------------------

// Printing: Matrix.

// matrix<string>
strMtx  = tools._rndmStringMatrix()
printer.print(strMtx)

// matrix<float>
fltMtx  = tools._rndmFloatMatrix()
printer.print(fltMtx)

// matrix<int>
intMtx  = tools._rndmIntMatrix()
printer.print(intMtx)

// matrix<bool>
boolMtx = tools._rndmBoolMatrix()
printer.print(boolMtx)

// matrix<color>
clrMtx  = tools._rndmColorMatrix()
printer.print(clrMtx)

//-----------------------------------

// Printing: Title.

// Add a title.
printer.print(tools._rndmFloatArray(), title="Random float array")

// Change the orientation of title.
// Changing orientation for all titles.
printer.title(top=false)
printer.print(tools._rndmFloatArray(), title="Random float array")
printer.print(tools._rndmSentence(), title="Random sentence")
printer.print(tools._rndmFloatMatrix(), title="Random float matrix")

// Changing orientation for single title.
ts = titleStyle.copy(printer.titleStyle)
ts.top := false
printer.print(tools._rndmFloatArray(), title="Random float array", titleStyle=ts) // Will be changed.
printer.print(tools._rndmSentence(), title="Random sentence") // Back to default orientation.
printer.print(tools._rndmFloatMatrix(), title="Random float matrix") // Back to default orientation.

//-----------------------------------

// Printing: Styles.

// Add custom titleStyle and cellStyle to print method.
printer.print(tools._rndmFloatArray(), title="Random float array", titleStyle=customTitleStyle) // Custom titleStyle.
printer.print(tools._rndmSentence(), title="Random sentence", cellStyle=customCellStyle)  // Custom cellStyle.
printer.print(tools._rndmFloatMatrix(), title="Random float matrix", titleStyle=customTitleStyle, cellStyle=customCellStyle) // Both custom styles.
printer.print(tools._rndmIntArray(), title="Random integer array") // Back to default styles.

stack()

stack(): Used for changing the orientation of a printer object. By default, groups data and stacks it vertically. Setting this to false will print each group side by side.

// Turn off stacking.
printer.stack(false) 

// Turn on stacking (default).
printer.stack(true)

theme()

theme(): Used for adding a preset style combination to a printer object.

// Available themes:
// blue, gray (default), green, orange, pink, purple, red, white, yellow

// Set 'blue' theme.
printer.theme("blue")

// Set 'gray' theme.
printer.theme("gray")

// Set 'green' theme.
printer.theme("green")

// Set 'orange' theme.
printer.theme("orange")

// Set 'pink' theme.
printer.theme("pink")

// Set 'purple' theme.
printer.theme("purple")

// Set 'red' theme.
printer.theme("red")

// Set 'white' theme.
printer.theme("white")

// Set 'yellow' theme.
printer.theme("yellow")

title()

  • title(): Used for setting the position of of titles.
  • title(): Used for setting a custom titleStyle.
  • The last example assumes we already have a variable called customTitleStyle.
// Place titles on top (default).
printer.title(top=true) 

// Place titles on left.
printer.title(top=false) 

// Set a titleStyle.
printer.title(titleStyle=customtitleStyle)

Advanced Techniques

Beyond simple printing and basic customization, the print method offers extensive options for cell coloring in various ways. You can apply static coloring by customizing colors using the cellStyle object. For dynamic coloring based on values or conditions, you can utilize the dynamicColor object within the cellStyle. Additionally, you have the flexibility to use separate dynamicValues for color mapping. It's important to note that you can apply coloring to either the background or the text itself, providing a wide range of possibilities for visual representation. Let's explore some example usages below.

Example 1: Let's say we have a string array containing these values: Win, Loss, Breakeven. We would like to color Win with green, Loss with red, and Breakeven with yellow.

// An example string array containing our conditional string values.
conditionStringArr = array.from('Win', 'Win', 'Breakeven', 'Loss', 'Win', 'Breakeven', 'Loss')

// Create a new cellStyle object or for convenience, grab a copy from the printer object.
cs = p.cellStyle.copy(printer.cellStyle)

// Setup the dynamicColor object and apply to cellStyle.dynamicColor.
cs.dynamicColor := p.dynamicColor.new(
  up = color.lime, // ............................... This is the color for 'up' condition.
  down = color.red,  // ........................... This is the color for 'down' condition.
  neutral = color.yellow,  // .................. This is the color for 'neutral' condition.
  stringUp = 'Win',  // .......................... Set the string value for 'up' condition.
  stringDown = 'Loss', // ...................... Set the string value for 'down' condition.
  stringNeutral = 'Breakeven', // ........... Set the string value for 'neutral' condition.
  offsetItem = 'bg', // Use 'bg' when targeting text. Use 'text' when targeting background.
  offsetColor = color.black) // ........ Optionally, set a static color for the offsetItem.

// Now just pass the string array, along with the custom cellStyle to the print method.
p.print(conditionStringArr, cellStyle = cs)