Toolbars

The Omnis Studio toolbar class can not be instantiated in a subwindow.

In the StudioWorks framework we want each sub-window to be self-contained so we created a toolbar which can be instantiated inside a subwindow.

The toolbar is actually a subwindow with button objects. The developer declares the buttons which are to be displayed in the toolbar and then enables and disables each button as needed. The toolbar buttons have icons and text. The toolbar subwindow automatically removes the button text if there is insufficient room to display both the icons and text.

In StudioWorks a window which contains several subwindows can have a toolbar for each subwindow. The container window can make the subwindow toolbars visible or hidden as needed.

Toolbar Methods

The following methods are involved with setting subwindow toolbars.

• $:ToolbarClassName - Specifies the subwindow class name for the toolbar. Normally, swToolbar.
• $:ToolbarCmndsCSV - Specifies the button to appear on the toolbar.
  
  This method must simply return a CSV text string of the toolbar buttons. You can not include calculations, if/else, or a pick() function in this method. Code that includes calculations will break when the class is runtimized. To dynamically control toolbar buttons use methods which enable/disable commands, or the $removeCmnd, or the $removeToolbarButton method.
• $:ToolbarVisible.$assign - Use to hide or show the toolbar.
• $_constructToolbar - During the window construct, if there is a $:ToolbarClassName and a $:ToolbarCmndsCSV, this method sets the toolbar subwindow $classname property, initializes the buttons, and attaches the $cinst as a toolbar buttons observer so that when a button is pressed a $doCmnd message is sent to the window instance.

Commands Methods

Each toolbar button is normally mapped to a command. Toolbars and menus often share the same commands. The following methods are involved with controlling commands which therefore also control enabling/disabling toolbar buttons.

• $:CmndFactorsRow - Returns a row variable which describes the current state of different factors which affect the decision to make certain commands active or inactive.
  
  For example the command factors row may have a boolean column named, modified, which is set to true or false by various class methods ($control, $save, $cancel). The Save command button would be enabled/disabled based on the value of the modified column in the command factors row.
• $removeCmnd - Removes a command from the enabled commands CSV and removes the button from the toolbar.
• $updateActiveCmnds - update the active commands list and then enable/disable the toolbar buttons based on the command factors row, active commands list, and enabled commands CSV. This method also sends an $updateActiveCmnds message with the list of active commands to the parent window so that the parent has an opportunity to update the state of other GUI objects which might be affected by a change in the active commands list.
• $_constructEnabledCmndsCSV - During the window construct this method sets the ivar, iEnabledCmndsCSV, which is the set of commands that the subwindow will respond to. If a $doCmnd message is sent to the subwindow to execute a command which is not enabled, the subwindow will not process the request.
  
  For example if the user does not have permission to delete records for a window instance the Delete command would not be added to the enabled commands CSV during the construct. This would prevent the user from deleting a record, even if the GUI had the Delete button or menu item enabled.
• $_retActiveCmndsList - Returns a list of the currently active commands. Some commands could always be active, others may only be active depending on the state of one or more factors in the $:CmndFactorsRow.

Commands Methods Code

Because there are so many commands methods it can be confusing to figure out which method to override when you want to add, change, or modify commands.

The normal sequence of calls with the commands methods is as follows:

1. When a window is instantiated the $construct method of the window calls $_constructEnabledCmndsCSV.
2. By default the $_constructEnabledCmndsCSV starts with the $:ToolbarCmndsCSV and then checks user permissions for new, edit, delete permissions. Any command the user is not authorized for is removed by calling the $removeCmnd method. The $removeCmnd method deletes the command from the iEnabledCmndsCSV and removes it from the toolbar.
   
   The iEnabledCmndsCSV variable is normally only calculated once, during the $construct of the window instance.
   
   You override the $_constructEnabledCmndsCSV to add or remove commands from the iEnabledCmndsCSV variable. The iEnabledCmndsCSV only controls which commands the user is permitted to execute in a window instance.
3. After the window has been constructed it should receive a $_setMode message. The $_setMode method calls $updateActiveCmnds.
4. $updateActiveCmnds calls $:CmndFactorsRow.
5. $:CmndFactorsRow returns a row variable. Factors which affect whether or not a command should be active are added to the command factors row.
   
   In an edit window the current state of $:Modified could affect whether or not certain buttons are active, so a modified column is added to the command factors row and set to the current state of the $:Modified property.
   
   In a list window the number of selected lines could affect whether or not certain buttons are active so a linesselected column is added to the command factors row and set to the number of lines currently selected in the list.
   
   StudioWorks developers can override the $:CmndFactorsRow method, Do inherited Returns Row, and then add whatever command factor columns they like and set the current value for each added column.
6. The $updateActiveCmnds method then call the $_retActiveCmndsList method passing in the command factors row as a parameter.
7. The $_retActiveCmndsList method returns a single column list of all the commands which are currently active. Some commmands might always be active, others will be active depending on the values in the command factors row that is passed to the method. For example the Delete command will only be active in the headed list window if linesselected is greater than zero. The Edit command will only be active if linesselected=1. The Save command will only be active if modified=1.
   
   StudioWorks developers can override the $_retActiveCmndsList method to control which commands are active. Whether or not you use the $:CmndFactorsRow value to decide whether or not a command is active is up to you. If you want a command to always be active you simply add it to the active commands list which is returned by this method.
8. For security purposes the $updateActiveCmnds method takes the list of commands that is returned by $_retActiveCmndsList and checks it against the iEnabledCmndsCSV removing any active commands that are not in the enabled commands CSV.
9. The $updateActiveCmnds method checks if there is a toolbar visible and if so it sends a $setActiveCmnds message to the toolbar with the active commands list included as a parameter. The toolbar then enables/disables its buttons based on whether or not the buttons' commands is in the active commands list.
10. The $updateActiveCmnds then sends an $updateActiveCmnds message to its parent window if a parent exists and has the method. This allows the parent to set its toolbars etc. if needed.

StudioWorks developers wanting to modify commands related code would normally override methods as follows:

1. $:ToolbarCmndsCSV - to add/remove commands from a toolbar and the enabled commands CSV.
2. $_constructEnabledCmndsCSV - to add/remove the initial commands which can be executed by the current user in the window instance and are not already in the toolbar commands CSV.
3. $_retActiveCmnds - to control which commands are enabled or disabled when factors that affect those commands are changed.
4. $:CmndFactorsRow - to add columns to the command factors row and set their values. The command factors row values are used in the $_retActiveCmnds method for deciding which commands to include in the active commands list. You could also use the $:CmndFactorsRow in other custom methods or field handling to enable/disable entry fields, etc. The command factors row can also be used by the parent window.

Adding a Toolbar Button

The section takes you through the steps for adding a toolbar button to a subwindow. In this example we will add a button named Custom to the toolbar. Since buttons are mapped to commands, we also need to a command named Custom to the window's commands.

1. Create a concrete window class for the window instance if one doesn't already exists. Programmer Menu > Window Instances Browser
2. Select the window instance which you need a concrete class and click the Developerize button. This creates a new window class in the target library by the name of the WinInstID prefixed with the letter w.
3. F2 > select the new window class > F8 to go to the window class methods.
4. Make sure $:ToolbarClassName returns wToolbar or another valid toolbar subwindow class name.
5. Override $:ToolbarCmndsCSV and add Custom to the CSV string returned by the method. By default any commands returned by this method are automatically added to the $:EnabledCmndsCSV.
6. Override $_retActiveCmnds and add the following code.
   
   

   Do inherited Returns List
   Do List.$add('Custom')
   Quit method List

   
   
   This adds Custom as an active command for any state. If you want Custom to be state sensitive study the superclass code for this method and modify the method accordingly. If you want to create your own state factor, override and modify the $:CmndFactorsRow method.
7. Add a $custom method to the class method and put a Breakpoint command in the method. This method will be called after the user clicks the Custom button in the subwindow toolbar. The message will be sent via the $doCmnd method.
8. Close the window class method editor.
9. Add Custom to the menus string table schema class, sMn_stb, in the target library. Enter Custom for the column name and description. This will be the text for the toolbar button. If applicable you can include a back quote delimited tooltip in the description.
10. Add Custom to the icons schema class, sIcons, in the target library. Enter Custom for the column name and 1655 for the description. This will set the icon to a checkmark for the toolbar button.
11. Programmer Menu > Reload String Tables. This also rebuilds the menus and icons lists.
12. Open the window instance. The Custom button should appear in the toolbar. Clicking the button should take you to the breakpoint in the $custom method where you can then add the code to be executed when the subwindow receives a $custom command message.

Toolbar Appearance

There are several toolbar property methods you can access at any time to control the appearance of the toolbar.

1. $:IconsOnly - The toolbar shows icons and text if there is sufficient space. If there is not enough space, the toolbar removes text from some of the icons until there is enough room to fit the mix of icons with and without text. If you continue to shrink the width of the window you will eventually just all icons without any text. The $tooltip property will dispay the toolbar button text. To set the toolbar to icons only:
   
   

   Do irswToolbar.$:IconsOnly.$assign(kTrue) Returns FlagOK

2. $:Underline - The toolbar is instantiated in a subwindow field with the $effect property set to kBorderNone. Use this method if you want a visual line between the bottom of the toolbar and the rest of the window.
   
   

   Do irswToolbar.$:Underline.$assign(kTrue) Returns FlagOK

You must send the toolbar appearnce messages from your subwindow to its wToolbar instance. The $_constructToolbar method is a good place to do this.

Toolbar Troubleshooting

The following are some problems you might run into with StudioWorks toolbars and the solution:

1. Toolbar Buttons Not Positioned Correctly - If you see all of the toolbar buttons stacked on top of each other on the left side of the toolbar, the toolbar is not being sent a $resize message. If one of the superclasses of your subwindow is wBase_ToolbarTitlebar_abstract, you will find that its $eventResize method sends the $resize message to the toolbar. Your subwindow should be instantiated inside wShell which sends the subwindow an $eventResize message when the window is constructed. One way or another the toolbar needs to be sent a $resize message. Thist will solve your problem.
2. Toolbar Buttons Disabled - If the toolbar buttons are not being enabled, the toolbar is not being sent a $setActiveCmnds message. If one of the superclasses of your subwindow is wBase_ToolbarTitlebar_abstract, you will find its $updateActiveCmnds method sends the $setActiveCmnds(iActiveCmnds) message to the toolbar. The $updateActiveCmnds is normally called by $_setMode which is called by various other methods. One way or another your toolbar needs to be sent a $setActiveCmnds message with the CSV string of active commands as the parameter. Doing this and your toolbar buttons will be activated.

Button Modes - OK and Cancel

You can set the $buttonmode for specific toolbar buttons to kBMok and kBMcancel so that the toolbar button will be clicked when the user presses the Return key or Esc/Cmnd+. respectively.

The edit window defaults are set so that Save & Close is kBMok and Cancel is kBMcancel.

You can override these defaults with the $_setToolbarButtonModes method.

Do irswToolbar.$setButtonMode('SaveAndClose',kBMok) Returns FlagOK
If FlagOK
   Do irswToolbar.$setButtonMode('Cancel',kBMcancel) Returns FlagOK
End If
Quit method FlagOK

StudioWorks Documentation - Copyright 2005 Vencor Software