Add Custom Title Bar Elements

Add custom icons and tools to your application's title bar by adding a user-defined source file to the root of your application directory.

Please note the functions required to add your custom Titlebar items:

" .AddTool() "

Adds the submodule describing the tool appearance to the title bar.

Parameters:

Context Context object in which the function will execute, in this instance it should be "Self" by default, in reference to the title bar.
Callback String name of the new module constituting the tool. "Tool" in the scripting example following the below steps.
Parameters Optional parameter dictionary. Enter 'Invalid' if not needed.
Tool Visibility Boolean pointer. Signals whether to render the title bar item in the UI.
Example Usage TitleBarObject.AddTool(Self, "Callback Module Name", ParmDict, &ToolVis);

 

" .AddToolButton() "

Adds the submodule describing the button tool appearance and functionality within the title bar.

Parameters:

Context Context object in which the function will execute, in this instance it should be "Self" by default, in reference to the title bar.
Callback String name of the new module constituting the tool behavior. "BtnCallback" in the scripting example following the below steps.
GreyImage String file path image used to indicate the tool's disabled state. Enter 'Invalid' if not needed.
DownImage String file path image used to indicate the tool's pressed down state. Enter 'Invalid' if not needed.
UpImage String file path image used to indicate the tool's unpressed state. Enter 'Invalid' if not needed.
PtrState

Pointer towards a number indicating the state of the button:

  • 0 - Disabled

  • 1- Down

  • 2- Up

A state of '0' will disable the 'Callback' while '1' or '2' will enable it.

PtrToolTip Pointer towards the tool's tool-tip object. Enter 'Invalid' if not needed.
PtrToolTipBold Pointer towards the tool's tool-tip title. Enter 'Invalid' if not needed.
PtrToolVisible Boolean pointer. Signals whether to render the title bar item in the UI.
Example Usage TitleBarObject.AddToolButton(Self, "Callback Module Name", "Path\To\GreyImage.png", "Path\To\DownImage.png", "Path\To\UpImage.png", &ButtonState, &ButtonToolTip, &ButtonToolTipBold, &ButtonVisibility);

 

Steps to Create a Blue tool and a Plus button that increments its tool tip value:

  1. Navigate to the root of your application folder and create a new file named "TitleBarCustomToolController.SRC"

  2. In the same folder, open "AppRoot.SRC" in your choice of text editor and add this reference to your new file at the bottom. Be sure to do so before the last square bracket and add an informative comment nearby.

    Add "TitleBarCustomToolController Module "TitleBarCustomToolController.SRC";" to your AppRoot

  3. Back in your "TitleBarCustomToolController.SRC" file, add the following as a starting point. Please note, that "TitleBarCustomToolController" is the required name for the module.

    {======================== TitleBarCustomToolController =======================}
    {              Adds a '+' Button and a Blue Square to the titlebar            }
    {=============================================================================}
    (
    	TBar                        { The toolbar to modify                         };
    	ToolsDrawn                  { [OUT] whether any of the custom tools are
    		                      currently drawn, set by this module           };
    	ButtonToolWidth             { Width that tools attempting to appear like
    				      tool buttons should declare                   };
    )
    [
    	BtnState                    { State of button                               };
    	BtnTooltip                  { Tooltip for button                            };
    	BtnVis                      { Whether the button is visible                 };
    	BtnCallback          Module { Callback for button                           };
    	ToolVis                     { Whether the tool is visible                   };
    	Tool                 Module { The code to draw the tool                     };
    ]
    
    Init [
           If 1 Main;
           [
             { Use AddTool and AddToolButton to add more items to the toolbar }
             ToolVis = TRUE;
    	  TBar.AddTool(Self     { Context        },
    	  "Tool"   { Callback       },
    	  Invalid  { ParmDict       },
    	  &ToolVis { PtrToolVisible });
    	  BtnState = 2;
    	  BtnTooltip = 0;
    	  BtnVis = TRUE;
    	  TBar.AddToolButton(Self                             { Context        },
    			     "BtnCallback"                    { CallBack       },
    			     Invalid                          { GreyImage      },
    			     "Resources\ToolBarIcons\Add.png" { DownImage      },
    			     "Resources\ToolBarIcons\Add.png" { UpImage        },
    			     &BtnState                        { PtrState       },
    			     &BtnTooltip                      { PtrToolTip     },
    			     Invalid                          { PtrToolTipBold },
    			     5BtnVis                          { PtrToolVisible });
    
            ]
    ]
    
    Main [
    	{ ToolsDrawn should be set to true if any user defined tools are drawn,
    	  false if none are drawn. }
    	ToolsDrawn = ToolVis || BtnVis;
    ]
    
    <
    {================== TitleBarCustomToolController\BtnCallback =================}
    {                     Callback when the button is pressed                     }
    {=============================================================================}
    BtnCallback
    
    Main [
      If 1;
      [
        { Modify this code to change the behaviour of the ToolButton when clicked }
        BtnTooltip++;
        Return();
      ]
    ]
    
    { End of TitleBarCustomToolController\BtnCallback }
    >
    
    <
    {===================== TitleBarCustomToolController\Tool =====================}
    {                            Draws a custom tool                              }
    {=============================================================================}
    Tool
    [
      Width = 31                  { Width for toolbar                             };
      BtnLeft                     { Left of button                                };
      BtnTop                      { Top of button                                 };
      BtnRight                    { Right of button                               };
      BtnBottom                   { Bottom of button                              };
    ]
    
    Init [
      If 1 Show;
      [
        UnTransform(Self);
      ]
    ]
    
    Show [
      Return(Self);
    
      BtnLeft   = GetXformRefBox(Self, 0);
      BtnBottom = GetXformRefBox(Self, 1);
      BtnTop    = GetXformRefBox(Self, 3);
      { The reference box extends all the way to the last pixel before the next
        tool, so we'll calculate the right side of the box so that it's a square. }
      BtnRight  = BtnLeft + (BtnBottom-BtnTop);
      Width     = ButtonToolWidth;
    
      { Modify this code to change the appearance and behaviour of the tool.
        Unlike ToolButtons, standard tools don't have callbacks called by the
        toolbar when clicked. If a button with the same shape and size as all
        existing tools is desired, the coordinate calculations above should be
        kept as they are. Width must be valid or the tool will not be drawn. }
        ZBar(BtnLeft,
    	  BtnBottom,
    	  BtnRight,
    	  BtnTop,
    	  "<FF0000FF>");
    ]
    
    { End of DisplayManager\TitlebarMain\ShowBatt }
    >
    

  4. Select the 'Import File Changes' icon in your application element within your VTScada Application Manager.
  5. Observe the Title bar of your application. If the above example is used, it will look something like this:

    Custom elements will now appear in the title bar to the right of the VTScada logo.