ToolBar - Usage tutorial

ToolBar is a control which allows you to create a pane with buttons in a row or in a column. Each button is a tool in ToolBar’s context which you can click and select it. The tools are oriented either horizontally or vertically. The amount of tools per ToolBar’s client area is given by the developer. The space for each tool is then divided evenly throughout its client area.

For example, if ToolBar’s size is (width = 200, height = 30), ToolsPerPage = 5 and Orientation = Horizontal, then ToolBar will create space for 5 horizontally oriented tools, each of size (width = 40, height = 30).

If there are more tools in the ToolCollection that fit on ToolBar’s client area, the user can flick the finger across it to bring-in another page of tools.

Description of some properties:

Adding tools to ToolBar

1. First of all we’ll start with creating a TForm for the project.
   1. Right-click your project in solution explorer and click Add New Item…
      
   2. Click Windows Forms in Categories section and then choose Inherited Form in the Templates section. Give your inherited form a name (e.g., Form1) and then click the ‘Add’ button.
   3. On Inheritance Picker window click Browse and browse to the folder where you installed iPack (typically c:\program files (x86)\Bee Mobile\iPack\Bee Mobile Controls CF3.5) and choose BeeMobile.TransparentControls.CF3.dll file.
   4. The list of inheritable objects contained in the selected library will appear.
   5. Double click TForm and it will be added to your project.
2. With TForm added to your project set a BackgroundImage for it.
3. Put ToolBar on the form in Visual Studio designer.
4. Right click it and then click Properties.
5. Set the Dock property to: DockStyle.Bottom.
6. Set the height of ToolBar to 50.
7. Your Visual Studio Designer should now look similar to this:
   
8. Notice that the background of the ToolBar is gradient-filled and semi-transparent. You can specify the level of opacity with Opacity property. Also you can define the colors of gradient-fill with GradientBackground and GradientBackgroundFocused properties (the background will be gradient-filled using GradientBackgroundFocused colors if the ToolBar receives input focus). Set the Color1 of GradientBackground to 128, 192, 255 and Color4 to 0, 128, 255. Erase the values for Color2 and Color3.
   
9. Similarly you can set the BorderColor and BorderColorFocused properties. If you wish no border to be displayed, set a value of Transparent to these properties.
10. Find the ‘Tools’ property and click the ‘…’ button to open the Tool Collection Editor.
11. Add 8 Tool objects. For now we will only set those Tool properties which fall into ‘Text’ category. Notice that the tools are separated by vertical lines (if you change the orientation of your Toolbar to vertical, the separators will become horizontal lines, of course). You can turn displaying these separators off changing the ShowToolsSeparators property of ToolBar to false.
12. Assign the following texts to the tools: Home, Contacts, Favorites, Alarm, Downloads, Info, Settings, Help
13. Now still in the Tool Collection Editor select all the tools and change their ForeColor and ForeColorSelected to White.
14. Change the FontSelected property for all the tools to: Tahoma, 9pt, style=Bold (once a tool is selected, the font will become bold).
15. You can align the text label anywhere within the area of a tool. By default, all of them are aligned to bottom and center of the tool’s area.
16. You will notice that even the text label is aligned to the bottom, there is still some space between the the text label and the bottom line of the tool. This is because there is a 2 pixels long margin set by default between the text label and the edge of the tool. You can expand the TextMargins property of a Tool and change the margins, if you like.

Adding images to tools

We will use the following images in this tutorial. Download them to your favorite directory on your hard drive.

The first step to add images to the tools is to load the images into the TImageCollection which you can access through Images property:

1. Click the ‘…’ button to bring-up TImage Collection Editor.
2. Click Add to add a new image.
3. Give a name ‘Home’ to your image.
4. Set ImageInDesigner property to the first (home) image (navigate to your favorite folder where you downloaded the images). You will notice that the image has immediatelly appeared over all the tools.
5. For the image to appear on the ToolBar during run-time we need to set either ImageFromFile or ImageFromResx property (but NOT both).
   
6. ImageFromFile is a path to the file which contains the image. If your image is contained in a file named ’01home.png’ then that is exactly what you would assign to this property. You also have to make sure that that file would be copied to the device.
7. ImageFromResx – we will use this variant in this tutorial.
   1. Make sure the image you are about to assign to this property is part of your project i.e., it appears in the solution explorer.
      
   2. Right-click that image in solution explorer and choose properties.
   3. Set Build-Action property to Embedded resource.
      
   4. Now find out the name of the default namespace of your project. Right-click your project in solution explorer and choose properties.
      
   5. In case of this project, the default namespace is ToolBarTutorialVB_CF35 (notice that the default namespace name of your project equals to the name of your project by default).
   6. Now go back to the TImage we edited before and set its ImageFromResx property to: [DefaultNameSpace].[ImageName] or in our case: ToolBarTutorialVB_CF35.01home.png
      
8. Notice in the Members section that the index of the Home image is 0.
9. Repeat steps 2 – 8 to add the remaining 7 images. Don’t forget to set both ImageFromResx and ImageInDesigner properties for each image.
10. This is how your ToolBar should look like now:
    
11. Go to Tool Collection Editor again. We are going to edit the properties which fall into the ‘Image’ category.
12. First of all we are going to set ImageMargins property for the Tools. The ImageMargins specify the distance between the edge of the image and the edge of tool in pixels. By default, this equals to (bottom, left, right, top) = (0;2;2;2). The text label overlaps with the image which is not what we want. Increase the bottom margin to value 20. By doing this you force ToolBar always to leave a distance between the bottom edge of the image and bottom edge of the tool of 20 pixels.
13. The image is now, however, distorted, which is not what we want. Return the Bottom margin value back to number 2 and set StrechImage property to false instead. Do that for all the tools in the Tool Collection.
14. Notice that you can also align the image using ImageAlignment property. Using this property together with ImageMargins – you can position the image pretty much anywhere within the tool.
15. The ImageIndex and ImageSelectedIndex define the index of an image in TImage Collection which should appear in the tool when it is not selected and when it is selected. In this tutorial we will use the same image for selected tool as well as non-selected tool. Assign an index of 0 to both of these properties for the Home tool, index of 1 to both of these properties for the Contacts tool, etc.
16. Click OK to confirm the changes and close the Tool Collection Editor.
17. To view the second page of tools in the designer, set ActivePage property to 1.

Cursor settings

ToolBar can display a graphical cursor in the form of round rectangle under the selected tool. This functionality is turned on by default. You can turn it on or off using DisplayCursor property.

The explanation for the properties can be found in the first section of this tutorial.

Events

Handle the SelectedToolIndexChanged event to handle the change  of SelectedToolIndex property.

If you have any questions or suggestions on this tutorial, please send us a feedback at support@beemobile4.net. Your feedback is appreciated. Thank you.