### Adding Toolbars

The toolbar is essentially a frame extension with buttons that represent common actions. You can add both fly-over help and drag-and-drop support on the toolbar. You can use the direct manipulation support to rearrange the toolbar buttons within an application or add new buttons from a menu (PM only).

The following figure shows an example of a tool bar.

This figure is created using the sample code found in the `ibmcppw\samples\ioc\tbar1` directory.

You can construct objects from the IToolBar class in the following ways:

1. The following IToolBar constructor creates a toolbar as the last toolbar in the toolbar area defined by the frameLocation. If groupWithPreceding is true, the toolbar is placed on the same row or column as the previous toolbar, if one exists. If an IToolBarContainer is needed for the location indicated, it is created when you use this contructor.

               IToolBar ( unsigned long          identifier,
                  IFrameWindow*          owner,
                  Location               location = aboveClient,
                  bool                   groupWithPreceding = false,
                  const Style&           style=defaultStyle());

2. Alternatively, you can construct a toolbar relative to an existing toolbar created with the first constructor (or with this constructor). This constructor adds the toolbar to the IToolBarContainer created when the precedingToolBar was created as follows:

               IToolBar ( unsigned long          identifier,
                          IToolBar*              precedingToolBar,
                          bool                   groupWithPreceding = false,
                          const Style&           style=defaultStyle());

#### Customizing Your Toolbar

When you create an object from the IToolBarButton class, you can use a standard format to ensure that all your buttons have the same common appearance. Standard formatting controls the amount of area occupied by the bitmap (when visible) and the amount of area occupied by text (when visible). Standard formatting affects all of the toolbar buttons that have a style of IToolBarButton::standardFormat. The Open Class Class Library takes advantage of the standard formatting of toolbar buttons when painting the button. This therefore improves the performance.

The nested classes IToolBar::Style and IToolBarButton::Style provide a set of valid styles you can use upon construction for objects of the class.

#### Toolbar Example

The following example shows a customized toolbar that implements fly-over help, direct manipulation support, and floating toolbars. This sample is found in the `ibmcppw\samples\ioc\tbar2` directory.

First, we do the following in the .hpp file:

1. Define the main window for our MLE on lines 121 through 127.
2. Define our toolbars on lines 141 through 144.
3. Define the buttons we want to place on our toolbar on lines 157 through 165.
4. We also define our toolbar settings notebook on lines 177 through 186.

    114  //-------------------------------------------------------------------
    115  // Editor
    116  //
    117  // This class is the main window of the sample problem.  It is
    118  // responsible for creating and managing all of the windows that
    119  // are used.
    120  //-------------------------------------------------------------------
    121  class Editor : public IFrameWindow
    122  {
    123  public:
    124    Editor();
    125
    126  EditorMLE
    127   &editorWindow ( ) { return editWindow; }
    128
    129  IFont
    130   &editorFont ( ) { return editFont; }
    131
    132  Editor
    133   &updateFontToolBar ( );
    134
    135  IToolBar
    136   &toolBar ( unsigned long id );
    137
    138  private:
    139    ITitle
    140      title;
    141    IToolBar
    142      fileToolBar,
    143      editToolBar,
    144      fontToolBar;
    145  IFlyText
    146    flyText;
    147  IStaticText
    148    infoText;
    149  IFlyOverHelpHandler
    150    flyHelpHandler;
    151  EditorMLE
    152    editWindow;
    153  EditorCommandHandler
    154    commandHandler;
    155  FontSelectHandler
    156    fontSelectHandler;
    157  IToolBarButton
    158    openButton,
    159    saveButton,
    160    cutButton,
    161    copyButton,
    162    pasteButton,
    163    boldButton,
    164    italicButton,
    165    underscoreButton;
    166  IComboBox
    167    fontCombo;
    168  IMenuBar
    169    menu;
    170  IFont
    171    editFont;
    172  };
    173
    174  //-------------------------------------------------------------------
    175  // ToolBarNotebook
    176  //-------------------------------------------------------------------
    177  class ToolBarNotebook : public IFrameWindow
    178  {
    179  public:
    180    ToolBarNotebook ( Editor&   editor );
    181  private:
    182  Editor
    183    &editorFrame;
    184  INotebook
    185    notebook;
    186  };

    In the .cpp file we then do the following:

1. Construct and show the editor (MLE) main window on lines 68 through 71.
2. Construct toolbars within the main window constructor on lines 81 through 89.
3. Construct the fly-over help short and long text and help handler on lines 90 through 92.
4. Add our toolbar buttons to the toolbars on lines 133 through 151.
5. Add the toolbar titles for floating toolbars on lines 189 through 191.
6. Add handlers for events, including fly-over help on lines 219 through 242.

Note: Line numbers refer to the actual sample file.

    64 /******************************************************************************
    65 * main -  creates and shows the editor window                                 *
    66 ******************************************************************************/

     int main()
     {
       ICoordinateSystem::setApplicationOrientation(
               ICoordinateSystem::originLowerLeft );
        Editor editor;
        editor.show();
        editor.setFocus();
        IApplication::current().run();
        return 0;
     }

    75 /******************************************************************************
    76 * Class Editor::Editor - Constructor for the editor window                    *
    77 ******************************************************************************/
     Editor::Editor ()
      : IFrameWindow(ID_MAIN_WINDOW)
      , title(this)
      , fileToolBar(ID_FILE, this, IToolBar::aboveClient, false,
                    IToolBar::classDefaultStyle
                    | IToolBar::dragDrop)
      , editToolBar(ID_EDIT, &fileToolBar, true,
                    IToolBar::classDefaultStyle
                    | IToolBar::dragDrop)
      , fontToolBar(ID_FONT, &editToolBar, true,
                    IToolBar::classDefaultStyle
                    | IToolBar::dragDrop)
      , flyText(ID_FLYTEXT, this)
      , infoText(ID_INFOTEXT, this, this)
      , flyHelpHandler(&flyText, &infoText, 0, 0)
      , editWindow(ID_EDITOR, *this)
      , commandHandler(*this)
      , fontSelectHandler(*this)
      , openButton(IC_ID_OPEN,&fileToolBar, &fileToolBar,
                   IRectangle(), IToolBarButton::defaultStyle() |
                   IToolBarButton::dragDelete )
      , saveButton(IC_ID_SAVE,&fileToolBar, &fileToolBar,
                   IRectangle(), IToolBarButton::defaultStyle() |
                   IToolBarButton::dragDelete )
      , cutButton(IC_ID_CUT,&editToolBar, &editToolBar,
                   IRectangle(), IToolBarButton::defaultStyle() |
                   IToolBarButton::dragDelete )
      , copyButton(IC_ID_COPY,&editToolBar, &editToolBar,
                   IRectangle(), IToolBarButton::defaultStyle() |
                   IToolBarButton::dragDelete )
      , pasteButton(IC_ID_PASTE,&editToolBar, &editToolBar,
                   IRectangle(), IToolBarButton::defaultStyle() |
                   IToolBarButton::dragDelete )
      , boldButton(IC_ID_BOLD,       &fontToolBar, &fontToolBar,
                   IRectangle(), IToolBarButton::defaultStyle() |
                   IToolBarButton::transparentBitmap )
      , italicButton(IC_ID_ITALIC,     &fontToolBar, &fontToolBar,
                   IRectangle(), IToolBarButton::defaultStyle() |
                   IToolBarButton::transparentBitmap )
      , underscoreButton(IC_ID_UNDERSCORE, &fontToolBar, &fontToolBar,
                   IRectangle(), IToolBarButton::defaultStyle() |
                   IToolBarButton::transparentBitmap )
      , fontCombo(ID_FONTCOMBO, &fontToolBar, &fontToolBar, IRectangle(),
                   IComboBox::classDefaultStyle &~IComboBox::simpleType |
                   IComboBox::readOnlyDropDownType)
      , menu(ID_MAIN_WINDOW,this)
      , editFont()

     {
    126 /*-----------------------------------------------------------------------------|
    127 | Set the icon and the title                                                                |
    128 ------------------------------------------------------------------------------*/
        setIcon( id() );
        title.setTitleText(ID_MAIN_WINDOW);

    132 /*-----------------------------------------------------------------------------|
    133 | Add buttons to the file toolbar                                              |
    134 ------------------------------------------------------------------------------*/
        fileToolBar.addAsLast(&openButton,true)
                   .addAsLast(&saveButton);

     /*-----------------------------------------------------------------------------|
     | Add buttons to the edit toolbar                                              |
     ------------------------------------------------------------------------------*/
        editToolBar.addAsLast(&cutButton,true)
                   .addAsLast(&copyButton)
                   .addAsLast(&pasteButton);

     /*-----------------------------------------------------------------------------|
     | Add buttons to the font toolbar                                              |
     ------------------------------------------------------------------------------*/
        fontToolBar.addAsLast(&boldButton,true)
                   .addAsLast(&italicButton)
                   .addAsLast(&underscoreButton)
                   .addAsLast(&fontCombo,true);

    /*-----------------------------------------------------------------------------|
    | Set up the latchabable style for font property buttons                       |
    | Note: When in bitmapAndTextView, latching a toolbar button will show the     |
    | gray background for the bitmap.  To eliminate the gray background, set       |
    | the transparent color to gray and turn on the transparent style for the      |
    | button.  If you do not use the bitmapAndTextView and you have many buttons   |
    | with the latchable style, consider not enabling the transparent style as     |
    | transparency incurs additional overhead and increases performance time.      |
    ------------------------------------------------------------------------------*/
       boldButton.enableLatching();
       italicButton.enableLatching();
       underscoreButton.enableLatching();

       boldButton.setTransparentColor(IColor::kPaleGray);
       italicButton.setTransparentColor(IColor::kPaleGray);
       underscoreButton.setTransparentColor(IColor::kPaleGray);

    170 /*-----------------------------------------------------------------------------|
    171 | Load up front combo box with face names                                      |
    172 ------------------------------------------------------------------------------*/
        fontCombo.setLimit(10);
     #ifndef IC_MOTIF
        IFont::FaceNameCursor fontCursor;
        for ( fontCursor.setToFirst(); fontCursor.isValid(); fontCursor.setToNext())
        {
          IString faceName = IFont::faceNameAt(fontCursor);
          fontCombo.addAsLast(faceName);
          if (faceName.length() > fontCombo.limit())
            fontCombo.setLimit(faceName.length());
        }
     #endif
        updateFontToolBar();

    186 /*-----------------------------------------------------------------------------|
    187 | Set up titles for toolbars when floating                                     |
    188 ------------------------------------------------------------------------------*/
        fileToolBar.setFloatingTitle(ID_FILE);
        editToolBar.setFloatingTitle(ID_EDIT);
        fontToolBar.setFloatingTitle(ID_FONT);

     /*-----------------------------------------------------------------------------|
    | Setup the editor                                                             |
    ------------------------------------------------------------------------------*/
       setClient(&editWindow);
       editWindow.setFont(editFont);
       try
       {
         editWindow.importFromFile("toolbar2.not");
       }
       catch( ... )
       {
          IMessageBox
             msgBox( this );
          msgBox.setTitle( STR_MSGBOX_TITLE );
          msgBox.show( STR_FILE_NOT_FOUND,
                       IMessageBox::okButton |
                       IMessageBox::warningIcon);
       }
       editWindow.setTop(1);

    /*-----------------------------------------------------------------------------|
    | Add the info frame extension                                                 |
    ------------------------------------------------------------------------------*/
       addExtension(&infoText, IFrameWindow::belowClient);

    218 /*-----------------------------------------------------------------------------|
    219 | Set up and add the help handler                                              |
    220 ------------------------------------------------------------------------------*/
        flyHelpHandler.setLongStringTableOffset(OFFSET_INFOTEXT);
        flyHelpHandler.setDefaultText("\0");
        flyHelpHandler.handleEventsFor(&fileToolBar);
        flyHelpHandler.handleEventsFor(&editToolBar);
        flyHelpHandler.handleEventsFor(&fontToolBar);

     /*-----------------------------------------------------------------------------|
     | Attach the Command Handler to frame and toolbar                              |
     ------------------------------------------------------------------------------*/
        commandHandler.handleEventsFor(this);
        commandHandler.handleEventsFor(&fileToolBar);
        commandHandler.handleEventsFor(&editToolBar);
        commandHandler.handleEventsFor(&fontToolBar);

     /*-----------------------------------------------------------------------------|
     | Add the handler to change the font                                           |
     ------------------------------------------------------------------------------*/
        fontSelectHandler.handleEventsFor(&fontCombo);

        moveSizeToClient(IRectangle(IPoint(100,100),
                                    ISize(editFont.avgCharWidth()*80,
                                          editFont.maxCharHeight()*15)));
    }

The resulting MLE and toolbars are displayed below.

You can use the settings notebook to chose where the toolbar appears and what appears on each toolbar button. In the preceding figure, there are three toolbars with different tool bar buttons. The floating toolbar, containing the font information, has been pinned to the owner window. The edit tool bar has been placed on the bottom of the window and contains both text and bitmaps on the buttons.

The settings notebook for the toolbars is displayed below.

#### Creating Toolbar Buttons

For creating toolbar buttons, the Open Class Library supplies a set of bitmaps and associated bitmap and help text. These bitmaps are based on the IBM/Lotus approved set available for user interface application development.

The IBM/Lotus toolbar graphics consist of approximately 60 graphical images, each representing a common action. This collection was comprised from graphical images used in a number of IBM and Lotus applications.

The Open Class Library supplies these images (in the form of bitmaps), plus a few others for your use in toolbar buttons. In addition to the button bitmaps, the Open Class Library also supplies button text and short and long help text. The button text is used when toolbar buttons are set to text or to text and bitmap view. The help text is used to provide additional information to the user about the function of the button. The code samples display the short text for each button in fly-over help (sometimes called hover help), when the mouse is moved over a button. The samples display the long text for each button in an information area at the bottom of the main window. This text is also triggered by the movement of the mouse over a toolbar button.

The resource IDs for these common bitmaps are defined in the icconst.h file. The following figure shows the commonly used bitmaps shipped with the Open Class Class Library:

When you build applications that use toolbars or any other resources provided, you must supply the Open Class Class Library resource DLL with your application.

The following is a list of the new toolbar button bitmaps and their associated text. The identifier (ID) is used when creating the toolbar button.

Note: The \n in the button text of certain buttons indicates a line break. When toolbar button text is displayed, the \n is removed, and the remaining text is continued on the next line.

    ID:              IC_ID_CANCELOPERATION
    Button Text:     Cancel
    Short Help Text: Cancel Current Operation
    Long Help Text:  End the current operation and discard any changes

    ID:              IC_ID_EXIT
    Button Text:     Exit
    Short Help Text: Exit
    Long Help Text:  Leave the application

    ID:              IC_ID_OPEN
    Button Text:     Open
    Short Help Text: Open
    Long Help Text:  Open another document/object

    ID:              IC_ID_NEW
    Button Text:     New
    Short Help Text: New
    Long Help Text:  Create a new document/object and open it

    ID:              IC_ID_SAVE
    Button Text:     Save
    Short Help Text: Save
    Long Help Text:  Save your current work

    ID:              IC_ID_SAVE_AS
    Button Text:     Save As
    Short Help Text: Save As
    Long Help Text:  Save a copy of the current document/object with a new name

    ID:              IC_ID_LOCATE
    Button Text:     Find...
    Short Help Text: Find
    Long Help Text:  Find within the current document/object

    ID:              IC_ID_CUT
    Button Text:     Cut
    Short Help Text: Cut
    Long Help Text:  Cut the selected object to the Clipboard

    ID:              IC_ID_COPY
    Button Text:     Copy
    Short Help Text: Copy
    Long Help Text:  Copy the selected object to the Clipboard

    ID:              IC_ID_PASTE
    Button Text:     Paste
    Short Help Text: Paste
    Long Help Text:  Paste from the Clipboard

    ID:              IC_ID_PASTESPECIAL
    Button Text:     Paste\nSpecial...
    Short Help Text: Paste Special
    Long Help Text:  Paste, link, or embed from the Clipboard

    ID:              IC_ID_PASTELINK
    Button Text:     Paste Link
    Short Help Text: Paste Link
    Long Help Text:  Paste a link from the Clipboard

    ID:              IC_ID_HELP
    Button Text:     Help
    Short Help Text: Help
    Long Help Text:  Display help text

    ID:              IC_ID_GENERALHELP
    Button Text:     General\nHelp
    Short Help Text: General Help
    Long Help Text:  Display general help information

    ID:              IC_ID_HELPINDEX
    Button Text:     Help Index
    Short Help Text: Help Index
    Long Help Text:  Display an index of all the available help

    ID:              IC_ID_HELPTUTORIAL
    Button Text:     Tutorial
    Short Help Text: Take a Tutorial
    Long Help Text:  Take a tutorial explaining how to use the application

    ID:              IC_ID_USINGHELP
    Button Text:     Using Help
    Short Help Text: Using Help
    Long Help Text:  Learn how to use help

    ID:              IC_ID_DESELECTALL
    Button Text:     Deselect\nAll
    Short Help Text: Deselect All
    Long Help Text:  Deselect all objects

    ID:              IC_ID_SELECTALL
    Button Text:     Select All
    Short Help Text: Select All
    Long Help Text:  Select all objects

    ID:              IC_ID_INSERTCOLUMN
    Button Text:     Insert\nColumn
    Short Help Text: Insert Column
    Long Help Text:  Insert a column into the table

    ID:              IC_ID_DELETECOLUMNS
    Button Text:     Delete\nColumn
    Short Help Text: Delete Column
    Long Help Text:  Delete the selected column(s)

    ID:              IC_ID_INSERTROW
    Button Text:     Insert Row
    Short Help Text: Insert Row
    Long Help Text:  Insert a row into the table

    ID:              IC_ID_DELETEROWS
    Button Text:     Delete Row
    Short Help Text: Delete Row
    Long Help Text:  Delete the selected row(s)

    ID:              IC_ID_UNDO
    Button Text:     Undo
    Short Help Text: Undo
    Long Help Text:  Undo the last action you took

    ID:              IC_ID_REDO
    Button Text:     Redo
    Short Help Text: Redo
    Long Help Text:  Redo the action you just undid

    ID:              IC_ID_CHECKSPELLING
    Button Text:     Spelling
    Short Help Text: Check Spelling
    Long Help Text:  Check the spelling

    ID:              IC_ID_NORMAL
    Button Text:     Normal\nText
    Short Help Text: Normal Text
    Long Help Text:  Remove emphasis from the selected text

    ID:              IC_ID_ABOUT
    Button Text:     Product\nInfo
    Short Help Text: Product Info
    Long Help Text:  Version, copyright and legal information

    ID:              IC_ID_UPDATE
    Button Text:     Update
    Short Help Text: Update
    Long Help Text:  Update the current view

    ID:              IC_ID_MAILSEND
    Button Text:     Send...
    Short Help Text: Send This to Someone
    Long Help Text:  Send the current document/object to another person

    ID:              IC_ID_MOVEPAGES
    Button Text:     Move Page
    Short Help Text: Move Page
    Long Help Text:  Move the current page to another position

    ID:              IC_ID_PRINT
    Button Text:     Print...
    Short Help Text: Print
    Long Help Text:  Print the current document/object

    ID:              IC_ID_PRINTPREVIEW
    Button Text:     Print\nPreview
    Short Help Text: Print Preview
    Long Help Text:  See how the document looks when printed

    ID:              IC_ID_PRINTSETUP
    Button Text:     Print\nSetup
    Short Help Text: Print Setup
    Long Help Text:  Display the current settings for printing

    ID:              IC_ID_SORTAZ
    Button Text:     Sort A-Z
    Short Help Text: Sort Ascending (alphabetical)
    Long Help Text:  Sort the selected objects in ascending alphabetical order

    ID:              IC_ID_SORTZA
    Button Text:     Sort Z-A
    Short Help Text: Sort Descending (alphabetical)
    Long Help Text:  Sort the selected objects in descending alphabetical order

    ID:              IC_ID_SORTUP
    Button Text:     Sort 1-9
    Short Help Text: Sort Ascending (numeric)
    Long Help Text:  Sort the selected objects in ascending numerical order

    ID:              IC_ID_SORTDOWN
    Button Text:     Sort 9-1
    Short Help Text: Sort Descending (numeric)
    Long Help Text:  Sort the selected objects in descending numerical order

    ID:              IC_ID_SETTINGS
    Button Text:     Properties
    Short Help Text: Properties
    Long Help Text:  Show properties of the current document/object

    ID:              IC_ID_TOOLBAR
    Button Text:     Show\nToolbar
    Short Help Text: Show Toolbar
    Long Help Text:  Display the toolbar for the application

    ID:              IC_ID_TOOLBARSETUP
    Button Text:     Toolbar\nSetup
    Short Help Text: Toolbar Setup
    Long Help Text:  Customize the setup of your toolbar

    ID:              IC_ID_RUNSCRIPT
    Button Text:     Run\nScript...
    Short Help Text: Run a Script
    Long Help Text:  Run a script

    ID:              IC_ID_VPAPALETTE
    Button Text:     Show\nActions...
    Short Help Text: Show Actions and Properties You Can Add
    Long Help Text:  Show a palette of available actions and properties you can add to this application

    ID:              IC_ID_TOUR
    Button Text:     Tour...
    Short Help Text: Take a Tour
    Long Help Text:  Take a tour of the application's features and learn how to use them

    ID:              IC_ID_LEFTALIGNOBJ
    Button Text:     Left Align
    Short Help Text: Left Align Objects
    Long Help Text:  Left align the selected objects

    ID:              IC_ID_RIGHTALIGNOBJ
    Button Text:     Right Align
    Short Help Text: Right Align Objects
    Long Help Text:  Right align the selected objects

    ID:              IC_ID_ZOOM
    Button Text:     Zoom
    Short Help Text: Zoom
    Long Help Text:  Zoom selected area , so it fills the work area

    ID:              IC_ID_ZOOMIN
    Button Text:     Zoom In
    Short Help Text: Zoom In
    Long Help Text:  Zoom in closer to the current document/object

    ID:              IC_ID_ZOOMOUT
    Button Text:     Zoom Out
    Short Help Text: Zoom Out
    Long Help Text:  Zoom out farther from the current document/object

    ID:              IC_ID_LOGON
    Button Text:     Logon
    Short Help Text: Logon
    Long Help Text:  Log on to the system

    ID:              IC_ID_LOGOFF
    Button Text:     Logoff
    Short Help Text: Logoff
    Long Help Text:  Log off the system

    ID:              IC_ID_BOLD
    Button Text:     Bold
    Short Help Text: Bold
    Long Help Text:  Make the selected text bold

    ID:              IC_ID_ITALIC
    Button Text:     Italic
    Short Help Text: Italic
    Long Help Text:  Make the selected text Italic

    ID:              IC_ID_UNDERSCORE
    Button Text:     Underline
    Short Help Text: Underline
    Long Help Text:  Underline the selected text

    ID:              IC_ID_DOUBLEUNDERSCORE
    Button Text:     Double\nUnderline
    Short Help Text: Double Underline
    Long Help Text:  Double underline the selected text

    ID:              IC_ID_CENTER
    Button Text:     Align\nCenter
    Short Help Text: Align Center
    Long Help Text:  Center align the selected text

    ID:              IC_ID_LEFT
    Button Text:     Align\nLeft
    Short Help Text: Align Left
    Long Help Text:  Left align the select text

    ID:              IC_ID_RIGHT
    Button Text:     Align\nRight
    Short Help Text: Align Right
    Long Help Text:  Right align the selected text

    ID:              IC_ID_JUSTIFY
    Button Text:     Justify
    Short Help Text: Full Justify
    Long Help Text:  Fully justify the selected text

    ID:              IC_ID_CLEAR
    Button Text:     Clear
    Short Help Text: Clear
    Long Help Text:  Clear the selected object(s)

    ID:              IC_ID_DELETE
    Button Text:     Delete
    Short Help Text: Delete
    Long Help Text:  Delete the selected object(s)

The new Open Class toolbar bitmaps differ in some ways from the previous Open Class toolbar bitmaps. In addition to the change in the number of bitmaps, their size, default transparent state, and the number of lines needed to display text have changed.

The new bitmaps consist of the 61 listed above. There are also 13 available in the current product. Each of these is also included in the new group. The actual graphic depiction of these 13 is replaced with a new representation. The ID you use to refer to the current bitmaps references the new bitmaps.

You can still reference the current bitmaps by using a new ID that corresponds to these bitmaps. These new IDs are as follows:

- IC_ID_TRANS_NEW
- IC_ID_TRANS_ABOUT
- IC_ID_TRANS_OPEN
- IC_ID_TRANS_SAVE
- IC_ID_TRANS_PRINT
- IC_ID_TRANS_LOCATE
- IC_ID_TRANS_CUT
- IC_ID_TRANS_COPY
- IC_ID_TRANS_PASTE
- IC_ID_TRANS_HELP
- IC_ID_TRANS_BOLD
- IC_ID_TRANS_ITALIC
- IC_ID_TRANS_UNDERSCORE
- IC_ID_TRANS_SETTINGS
- IC_ID_TRANS_COPYTO

Each of the new bitmaps has a non-transparent gray background. This means that the solid background area of a bitmap does not show through the bitmap. Changing the default state of buttons from transparent to non-transparent is being done for performance. Displaying a bitmap with transparency involves creating a mask bitmap, which must be combined with the original bitmap and drawn to the screen. This operation is quite a bit slower than drawing a single non-transparent bitmap to the screen. In a toolbar with 10 or more buttons, this performance savings is clearly visible.

The background gray color selection is being carefully chosen. On Windows, the background gray has a Red, Green, Blue (RBG) value of (192,192,192). This matches the default gray used by Win32. On OS/2, the background RGB values are (204,204,204), to match the default gray used by OS/2 4.0.

To provide support for transparent buttons, we introduced a new style called IToolBarButton::transparentBitmap. If you want transparent behaviour for a particular button, you need to specify this style on button creation. In addition to specifying this style, you also need to define a color to be used for transparency. By default, a transparent color is initially defined. This color, pink, has an RGB value of (255,0,255). The following example sets up transparent behavior for one of the new button bitmaps:

       IToolBarButton * cutButton = new IToolBarButton(
                 IC_ID_CUT, &toolBar, &toolBar,
                 IRectangle(), IToolBarButton::defaultStyle() |
                 IToolBarButton::transparentBitmap);

       //By default, a transparenent color of RGB value (255,0,255) has
       //already been set.  Reset the color to match the background in the bitmap.
       IColor *transparentColor = new IColor(192,192,192);  //Win32
       cutButton->setTransparentColor(*transparentColor);

Each of the new bitmaps is slightly larger. This in turn makes the toolbar button slightly larger. This change is being made for the following reasons: The larger size makes the buttons more readable. There is more room to depict each graphical image. The buttons are symmetrically square rather than rectangular, which with their larger size, makes them more consistent with the Lotus Smart Suite applications and other Win32 applications.

The button sizes are as follows:

                            Current Bitmaps    New Bitmaps
                            ---------------    -----------
      Bitmap size:               20x17            22x22
      Resulting button size:     27x24            29x29

To differentiate between similar images and actions, the button text (which can be seen when the button is displayed in text or bitmap and text view) is two lines on some buttons. These are:

- IC_ID_PASTESPECIAL, with text of: "Paste\nSpecial..."
- IC_ID_GENERALHELP, with text of: "General\nHelp"
- IC_ID_DESELECTALL, with text of: "Deselect\nAll"
- IC_ID_INSERTCOLUMN, with text of: "Insert\nColumn"
- IC_ID_DELETECOLUMNS, with text of: "Delete\nColumn"
- IC_ID_NORMAL, with text of: "Normal\nText"
- IC_ID_ABOUT, with text of: "Product\nInfo"
- IC_ID_PRINTPREVIEW, with text of: "Print\nPreview"
- IC_ID_PRINTSETUP, with text of: "Print\nSetup"
- IC_ID_TOOLBAR, with text of: "Show\nToolbar"
- IC_ID_TOOLBARSETUP, with text of: "Toolbar\nSetup"
- IC_ID_RUNSCRIPT, with text of: "Run\nScript..."
- IC_ID_VPAPALETTE, with text of: "Show\nActions..."
- IC_ID_DOUBLEUNDERSCORE, with text of: "Double\nUnderline"
- IC_ID_CENTER, with text of: "Align\nCenter"
- IC_ID_LEFT, with text of: "Align\nLeft"
- IC_ID_RIGHT, with text of: "Align\nRight"

The default for standard buttons (those created with the IToolBarButton::standardFormat style) is still to display only one line of text on a button when the button is displayed in text or bitmap and text view. This is being left unchanged to maintain consistency with existing Open Class toolbar applications and because the majority of the buttons have only one line of text.

If you are using one of the pre-defined buttons above, and your toolbar buttons are standard format, you can set the default number of lines of text to be displayed for toolbar buttons to 2. You call IToolBarButton::setStandardTextLines, as follows:

      IToolBarButton::setStandardTextLines(2);

If you do not set the standard text lines to 2, the second line of text is not displayed.

The rationale behind adding a second line to display the extra text, is so that the toolbar lays-out better in an application. If the extra text were to be displayed on one long line, the buttons would need to be wide rectangular shaped to fit the text.

Each of the new toolbar bitmaps contains associated short and long help text. The help text is used to provide additional information to the user about the function of the button. Most often, application developers choose to display short text for a button in fly over help, which appears when the mouse is moved over a button. Developers often choose to display long text for a button in an information area at the bottom of a window. This text is also triggered by the movement of the mouse over a toolbar button.

You can still supply your own short and long help text, as you do in previous versions of Open Class. However, if you want to use the Open Class supplied help text, you can do so in only a few lines of code:

      //Tell the IFlyOverHelpHandler to search for text in the Open Class
      //supplied resource library.
      flyHelpHandler.setResourceLibrary(
        IApplication::current().resourceLibrary().fileName() );

      //Tell the IFlyOverHelpHandler the offsets for the help text.
      flyHelpHandler.setFlyTextStringTableOffset(IC_FLYTEXTOFFSET);
      flyHelpHandler.setLongStringTableOffset(IC_LONGTEXTOFFSET);

If you want to supply your own help text, first ensure that the IFlyOverHelpHandler's resource library is the one bound to your application (which is the default for IFlyOverHandler). Second, associate your text string with the button ID in your resource file. You can optionally define an ID offset, as is done above.

If you have an existing Open Class application, you get the new bitmaps automatically with no changes needed to your application. Of course, if you want to take advantage of the short and long help text, or use one of the added bitmaps that have two lines of button text, you need to make some modifications to your program.

To revert back to the current bitmaps, you need to change your application to use the new IDs that refer to these bitmaps. These IDs are listed above. Secondly, you need to create each button with the IToolBarButton::transparentBitmap style.

If the window ID is in the Open Class library reserved range, the bitmap and text are loaded from the Open Class Library's resource library. Otherwise, the bitmap and text are loaded from the default user defined resource library. If no bitmap is found in the appropriate library, a default bitmap is loaded.

Toolbars
Direct Manipulation

Providing Help Information
Using Default Direct Manipulation
Enabling Direct Manipulation
Adding Images to Drag Items

ICustomButton
IToolBar
IToolBarButton
IFlyOverHelpHandler
IFlyText