Tutorial 2

SDI Sample
In this sample program you will: Learn how to attach docking panes to an application. Learn how to attach panes create three docking panes that can be displayed in any combination along with the applications main document. Learn how to tell when a docking pane performs an action like open, close, or float You will create three docking panes that can be displayed in any combination along with the applications main document. The main document can be hidden from view so only the docking panes are in the client window. The splitter tracker is used when resizing a docking pane; the splitter tracker will only display a line indicating where the new docking pane boundary will be when the mouse button is let up.

Creating SDI
Figure 2.1.
What you can create in this sample

Opening the Application

Open Visual Basic and Select new project from the file menu. Select VB Application Wizard from the new project dialog box and click OK On the first step of the wizard, we do not have a profile so accept the default and continue. On the second step of the wizard, make sure that MDI is selected and give the project an appropriate name. Click Finish For this sample you will use the default command bar that Visual Basic creates

Adding Controls
Once the VB Application Wizard is finished, display the toolbox (View->Toolbox). Right-Click on an open area not occupied by a control and select Components from the pop-up menu. Project->Components will work as well. Select the Controls tab if it is not already selected and scroll down to the bottom. You should see Xtreme DockingPane ActiveX Control module, make sure that the check box is selected and click OK You should now have a new control added to your Toolbox that looks like this:

Figure 2.2.
Adding a new control

Now, add the Rich Text Box Control if it is not already in your toolbox. Follow the same steps as you did above, adding the Microsoft Rich Textbox Control 6.0. You should now have a new control in your toolbox that looks like this:

Adding the Controls to the Form

You will need to add the DockingPane, ImageList, and Rich TextBox controls to the main form. Place a DockingPane control (Red box in Figure 2.3.) on any blank area on your form. Click on the DockingPane control Go to the properties window Name it DockingPaneManager.

Figure 2.3.
Controls

Add a Rich Textbox control (Blue box in Figure 2.3.) to your form Click on the control Go to the properties window Change the name to rtfText Change the ScrollBars property to 3-rtfBoth Delete the text in the Text property as in the properties diagram in Figure 2.3. Add an ImageList control (Green box in Figure 2.3.) to your form Click on the control Go to the properties window Change the name to imlPaneIcons Change the ImageHeight and ImageWidth to 16. Visual Basic will create two controls: A CommonDialog control An ImageList control (Purple box in Figure 2.3.) (Purple box in Figure 2.3.)

Leave them on the form. You will not need to modify them.

Icons
Each docking pane will have an icon displayed on its tab when the pane is docked as in Figure 2.4.

Figure 2.4.
Docking Pane Tabs

Right-click on the imlPaneIcons ImageList control and select properties from the pop-up menu.

Figure 2.5.
Displaying Properties

There will not be any icons in the Images: List box (red box in Figure 2.6.) To add images, click on the Insert Picture button and navigate to the C:\Program Files\Codejock Software\ActiveX\Suite\samples\DockingPane\SDISample\Icons directory.

Insert incon1.bmp, incon2.bmp, and icon3.bmp as in Figure 2.6.

Figure 2.6.
Inserting Icons

The key and tag properties are not important in this project. Leave them as the default values. The index of the image will correspond to the ID of each docking pane. A MaskColor is needed to mask transparent content of an image. Each image has a background color of green that must be set as the transparent color. To do this click on the Color tab. Click on MaskColor (red box in Figure 2.7.) in the Properties box Select Green from the Color Palette (blue box in Figure 2.7.) Click the Apply button Click OK to finish.

It is recommended that you use a bitmap for your ImageList. Bitmaps will look much better than icons when displayed on the docking pane tabs.

Figure 2.7.
Setting the MaskColor

Adding the Pane Controls

There will be a control in the menu to access each docking pane. You will need to add three controls to the menu, one for each pane. The panes will be named PaneA, PaneB, and PaneC. To create the controls: Right-click on the grey area of your main form Select Menu Editor Scroll through the list of menu controls Click on the Refresh control Click the Insert button.

Figure 2.8.
Opening the Menu Editor

Figure 2.9.
The Menu Editor

Enter Pane A as the caption (red box in Figure 2.9.) Enter mnuPaneA as the Name (blue box in Figure 2.9.) The name is used as the Click event procedure. Click the Next button Click the Insert button Enter Pane B as the caption, and mnuPaneB as the Name. Do the same for Pane C. Click the Next button Click the Insert button

Enter a separator under Pane C by entering a hyphen ( - ) as the caption. Enter Hide Client as the Caption, and mnuHideClient as the Name. Click the Next button Click the Insert button Enter Use Splitter Tracker as the Caption, mnuUseSplitterTracker as the Name, and make sure the Checked option (green box in Figure 2.9.) has a check mark. Delete the Refresh, Options, and Web Browser controls from the menu. Click the OK button when you are finished entering all three controls. Your menu should look like Figure 2.10. below.

Figure 2.10.
Your Menu

Creating New Docking Panes

A separate form is used to create new docking panes. Add a new form to your project. Click on Project->Add Form Make sure Form is selected

10

Click the Open button

Figure 2.11.
Adding a New Form

Visual Basic will display a new form. With the new form selected, go to the properties window and change: 1. 2. 3. 4. 5. 6. Name to frmPane BackColor to Button Shadow BorderStyle to 0-None MaxButton to False MinButton to False ScaleMode to 3-Pixel

Figure 2.12
Properties of frmPane

Place a textbox control on the form (see Figure 2.13.) With the textbox selected, go to the properties window and change:

11

1. Name to txtContent 2. BorderStyle to 1-Fixed Single 3. Delete the description in the Text property

Figure 2.13
txtContext Properties

Available Events
Look at all of the available events the DockingPane control provides. There are two ways to do this: #1 Open up the object browser by hitting F2 Select XtremeDockingPane from the library list drop down menu

Figure 2.14.
Displaying available events

12

Select the DockingPane entry in the list box. Now you can see all of the available members, methods, events, properties, functions, and subs. If you click on a member you will get detailed information about that member. Here we are interested in the events available that have the lightning bolt icon next to them. #2 Go to your code view by hitting F7

Figure 2.15.
Displaying available events

The left drop-down is a list of your controls; the right drop-down is a list of event procedures available for those controls. Select the DockingPaneManager option from the left drop down list and browse the right drop down list for a list of event procedures available to the DockingPane control. It is this second method that we will be using to add code to the different DockingPane event Procedures.

Creating the Panes

Three panes of type frmPane must be created. Declare an array of three elements of type frmPane in the General code section. Name the array arrPanes.
Dim arrPanes(1 To 3) As frmPane

This array will contain the three panes that you will be docking in the application. With the array of panes declared, create three panes and dock them to the application. To do this, start coding the Form_Load event procedure of the main form as in the following code
Private Sub Form_Load() Me.Left = GetSetting(App.Title, "Settings", "MainLeft", 1000) Me.Top = GetSetting(App.Title, "Settings", "MainTop", 1000) Me.Width = GetSetting(App.Title, "Settings", "MainWidth", 6500) Me.Height = GetSetting(App.Title, "Settings", "MainHeight", 6500) Dim A As Pane, B As Pane, C As Pane Set A = DockingPaneManager.CreatePane(1, 200, 120, DockLeftOf, Nothing) A.Title = "Pane A"

13

Set B = DockingPaneManager.CreatePane(2, 200, 120, DockTopOf, A) B.Title = "Pane B" Set C = DockingPaneManager.CreatePane(3, 200, 120, DockTopOf, B) C.Title = "Pane C" DockingPaneManager.ImageList = imlPaneIcons DockingPaneManager.LoadState "Codejock Software Demos", "SDISample", "Layout" End Sub

Start by declaring three objects of type Pane, which represents a docking pane. Name them A, B, and C Create the three docking panes Use the DockingPaneManager.CreatePane method to create and dock the pane. The CreatePane method takes five parameters: 1. 2. 3. 4. 5. The ID of the pane The initial width of the pane in pixels The initial height of the pane in pixels The direction in which to dock the pane The neighboring pane that the pane will be docked to

The fifth parameter can be the keyword Nothing when you want to use the main frame as a neighbor. The ID should be the same as the index of the corresponding icon in the ImageList. In the example, Pane A is docked to Nothing. This will dock the pane to the main form. DockLeftOf is passed as a parameter. This places the docked pane on the left side of the main form. The pane will have an initial width of 200 pixels and height of 120 pixels.
Set A = DockingPaneManager.CreatePane(1, 200, 120, DockLeftOf, Nothing) A.Title = "Pane A"

Next, create panes B and C.

Set B = DockingPaneManager.CreatePane(2, 200, 120, DockTopOf, A) B.Title = "Pane B" Set C = DockingPaneManager.CreatePane(3, 200, 120, DockTopOf, B) C.Title = "Pane C"

Pane B is docked to the top of Pane A

14

Pane C is docked to the top of Pane B

All of these panes can be closed and hidden. The MDI sample explains how to change this default behavior.

Now associate the imlPaneIcons ImageList with the docking panes using the following code
DockingPaneManager.ImageList = imlPaneIcons

In the sample, the last state/position the docking panes were in when the application was closed will be loaded from the systems registry (how to save your settings to the registry in explained later in this tutorial). To do this, use the LoadState method.
DockingPaneManager.LoadState "Codejock Software Demos", "SDISample", "Layout"

This method takes three string parameters: 1. The Registry key 2. The Application Name 3. The Section (folder) in which the settings will be saved. So far, the panes have been created. Each element of the frmPane array needs to be associated/attached with a docking pane.

Saving the Users Settings

The next step is to make sure you save the state and position the docking panes were in when the user closed the application. Because the user will be able to close, hide, move, and resize the docking panes, you need a way to save their settings for the next time they open the application. Use the DockingPaneManager.SaveState method. The SaveState method saves the pane layout to the registry. The layout will be saved to the registry key path built from the RegistryKey, AppName and Section parameters as follows: HKEY_CURRENT_USER\Software\ + RegistryKey + AppName + "DockingPaneLayouts" + Section.
Private Sub Form_Unload(Cancel As Integer) Dim i As Integer DockingPaneManager.SaveState "Codejock Software Demos", "SDISample", "Layout"

15

'close all sub forms For i = Forms.Count - 1 To 1 Step -1 Unload Forms(i) Next If Me.WindowState <> vbMinimized Then SaveSetting App.Title, "Settings", SaveSetting App.Title, "Settings", SaveSetting App.Title, "Settings", SaveSetting App.Title, "Settings", End If End Sub

"MainLeft", Me.Left "MainTop", Me.Top "MainWidth", Me.Width "MainHeight", Me.Height

This method takes three string parameters: 1. Registry key 2. Application Name 3. Section (folder) in which the settings will be saved. The following line of code will save your applications command bar settings in the system registry under HKEY_CURRENT_USER\Software\Codejock Software Demos\SDISample
DockingPaneManager.SaveState "Codejock Software Demos", "SDISample", "Layout"

This should be the first line of code in your main applications Form_Unload event procedure.

The Action Event Procedure

Each time an action is performed on a docking pane, the Action event procedure is called. An action occurs when the docking pane is being attached, attaching, closed, closing, docked, docking, floated, floating, pinned, and pinning. When the Action event is triggered, it is passed the type of action, the pane performing the action, and whether the action was canceled. One use for this event might be if a user decides to close a docking pane, a dialog could be displayed with an appropriate message. To demonstrate how the Action event procedure works, add the code below to the DockingPaneManager_Action event procedure
Private Sub DockingPaneManager_Action(ByVal Action As XtremeDockingPane.DockingPaneAction, _ ByVal Pane As XtremeDockingPane.IPane, Cancel As Boolean) On Error Resume Next Dim Actions Actions = Array("PaneActionFloating", "PaneActionFloated", _ "PaneActionClosing", "PaneActionClosed", "PaneActionDocking", "PaneActionDocked", _ "PaneActionAttaching", "PaneActionAttached", "PaneActionPinning", "PaneActionPinned") Debug.Print "Action = "; Actions(Action); "; Title = "; Pane.Title End Sub

16

The type of action is passed in as an integer that is used as an index in the Actions array. For example, when a pane is closed, the Action event is triggered two times. 1. The first time, the index 2 is passed indicating the pane is closing. 2. The second time, the Action event is triggered an index of 3 is passed indicating the pane was closed. A Debug.Print line is used to display each action in the Immediate window of the Visual Basic development environment. Figure 2.16. shows the Immediate window after a few docking pane actions are triggered.

Figure 2.16.
Immediate window

Height of the Status Bar and Toolbar

The height of the status bar and toolbar must be found before the docking panes and rich text box can be sized and positioned on the form. The DockingPaneManager event procedure GetClientBordersWidth is where the positions of the docking panes and rich text box are determined. This event procedure will be called automatically so you will not directly call it in your code. Without this procedure, you would not see your status bar and the toolbar would be displayed over the docking panes and open document. To edit the GetClientBordersWidth event procedure: Go into the main forms code view by hitting F7 Select DockingPaneManager from the left drop-down list Select GetClientBordersWidth from the right drop-down list

17

Figure 2.17.
Selecting GetClient BordersWidth

GetClientBordersWidth takes four parameters of type Long. These parameters represent the top, bottom, left, and right borders of the application window as below
Private Sub DockingPaneManager_GetClientBordersWidth(Left As Long, Top As Long, Right As Long, _ Bottom As Long) If sbStatusBar.Visible Then Bottom = sbStatusBar.Height End If If tbToolBar.Visible Then Top = tbToolBar.Height End If End Sub

In the event procedure, the Top and Bottom parameters are updated based on whether the status bar or toolbar are visible. The parameters let the DockingPane control know where it can position the docking panes. To ensure the rich text box is the same size as the open document window, change the rich text boxs border size as in the code below. This means the rich text box will fill the entire form area not occupied by the status bar, toolbars, menubar, or docking panes. To do this, add the DockingPaneManager event procedure Resize, just as you added the GetClientBordersWidth. This event procedure will be called automatically so you will not directly call it in your code.
Private Sub DockingPaneManager_Resize() On Error Resume Next Dim Dim Dim Dim Left As Long Top As Long Right As Long Bottom As Long

DockingPaneManager.GetClientRect Left, Top, Right, Bottom rtfText.Move Left, Top, Right - Left, Bottom - Top rtfText.RightMargin = IIf(rtfText.Width > 400, rtfText.Width - 400, rtfText.Width) End Sub

This event procedure takes the same parameters as the GetClientBordersWidth event procedure.

18

1. Call the GetClientRect method passing in the parameters Left, Top, Right, and Bottom. This event procedure retrieves the dimensions of the client rectangle, that is, the area on the form which does not have any docking panes. The rich text box should fill the open area of the form. To do this, you use the methods of the rich text box. The rtfText.Move method is used to resize the rich text box with the Left, Top, Right, and Bottom parameters retrieved by the GetClientRect method, which will size the rich text box to fill the forms open area. If you need help with the rich text box and its methods, it is well documented in the Microsoft help documentation. To determine the right margin of the rich text box, you need to make a decision based on whether the width is greater than 400. The Immediate-If function (IIF) is used to evaluate the width of the rich textbox. The IIF function takes three parameters 1. The expression to evaluate 2. What should be done if the expression is true 3. The last happens if the expression is false. Check the Microsoft help files for more help using the IIf function.

Attaching the Frames to the Docking Panes

To attach the frames to the docking panes, edit the DockingPanesManager event procedure AttachPane as done in the previous steps. This event procedure will also be called automatically and does not need to be directly called in your code.
Private Sub DockingPaneManager_AttachPane(ByVal Item As XtremeDockingPane.IPane) 'If Form not create yet. If arrPanes(Item.Id) Is Nothing Then Set arrPanes(Item.Id) = New frmPane End If 'Attach Form to Pane Item.Handle = arrPanes(Item.Id).hwnd End Sub

The AttachPane event procedure is passed an object of type Pane called Item. This event procedure will be called for each docking pane created in the Form_Load.

19

In the event procedure, a new frame of type frmPane will be created and added to the arrPanes array. The array index will correspond with the ID of the docking pane
If arrPanes(Item.Id) Is Nothing Then Set arrPanes(Item.Id) = New frmPane End If

After a frame has been created, the frame is attached to the docking pane with the following code:
'Attach Form to Pane Item.Handle = arrPanes(Item.Id).hwnd

Set the Handle property of the docking pane to the Handle property of the frmPane frame in the array. The Handle property of the docking pane is the handle of the child window displayed in the pane.

Creating a Border
The Textbox placed on the frmPane form needs to fill the entire open form. You will resize the Textbox just as the rich text box resized. To do this, edit the Form_Resize event procedure of the frmPane frame as in the code below
Private Sub Form_Resize() On Error Resume Next txtContent.Move Me.ScaleLeft + 1, Me.ScaleTop + 1, Me.ScaleWidth - 2, Me.ScaleHeight - 2 End Sub

The txtContent control is being sized to fill the entire form. The frmPane form is using a pixel coordinate system. The txtContent.Move method is passed the Left, Top, Width, and Height of the frame. By adding one to the top and left and subtracting two from the width and height, you create a small visible area around the textbox that looks like a border.

20

Opening and Closing each Docking Pane Separately

The first time the application is run, all ten docking panes will be displayed with the options/properties that were set in the Form_Load. If the user closes them, they need a way to open them back up. Add some code to each Click event procedure of the menu controls for each pane. Open the code view of the main form and select mnuPaneA from the left drop-down list.

Figure 2.18.
Selecting mnuPaneA

This control will only have a Click event procedure. In each event procedure, you will want to invoke the appropriate ShowPane method. Add the code DockingPaneManager.ShowPane 1 in the mnuPaneA_Click event procedure
Private Sub mnuPaneA_Click() DockingPaneManager.ShowPane 1 End Sub

The only parameter passed is the panes ID. Repeat these steps for PaneB passing in 2, and PaneC passing in 3. With these event procedures complete, the user can open and close each docking pane individually.

21

Hiding the Client Window

The client window can be hidden, allowing the docking panes to be displayed in the area the client window occupied. In Figure 2.19., the client window is visible, and it is hidden in Figure 2.20.

Figure 2.19.
Visible Client Window

Figure 2.20.
Hidden Client Window

Open the code view of the main form Select mnuHideClient from the left drop-down list. This control will only have a Click event procedure

22

Add the following code to toggle the visibility of the client.

Private Sub mnuHideClient_Click() DockingPaneManager.Options.HideClient = Not DockingPaneManager.Options.HideClient mnuHideClient.Checked = DockingPaneManager.Options.HideClient End Sub

This will hide the entire client area, meaning the area not occupied by CommandBars, Docking Panes, StatusBar, etc. The Option.HideClient property of the DockingPane control is toggled to True/False each time the control is clicked. Then the checkmark next to the menu control Hide Client is toggled to indicate that the control is on or off.

Resizing the Border of a Docking Pane

When resizing the border of a docking pane that is attached to a form or other docking pane, a splitter (named for the mouse icon that appears) is displayed as the border is dragged to the desired position. There are two ways the splitter can be displayed when the border of the docking pane is resized. When using a splitter tracker, only a bar will be displayed as the border is resized. The bar will move indicating where the new border will be once the mouse button is released. The original border does not resize until the mouse button release. In Figure 2.21, splitter tracking is enabled as the top border of Pane B is resized. Only a bar is displayed.

23

Figure 2.21.
Splitter Tracking Enabled

Figure 2.22.
The resized pane

If splitter tracking is disabled, then the border of the docking pane is resized in real-time. As the border is dragged, the pane will constantly be resized until the mouse button is released. In Figure 2.23 as Pane B is resized, the whole border is moved, not just a bar

24

Figure 2.23.
Splitter Tracking Disabled

Figure 2.24.
Splitter Tracking Disabled

Open the code view of the main form Select mnuUseSplitterTracker from the left drop-down list. This control will only have a Click event procedure. Add the following code to toggle the use of the Splitter Tracker.
Private Sub mnuUseSplitterTracker_Click() DockingPaneManager.Options.UseSplitterTracker = Not DockingPaneManager.Options.UseSplitterTracker mnuUseSplitterTracker.Checked = DockingPaneManager.Options.UseSplitterTracker End Sub

25

The Option.UseSplitterTracker property of the DockingPane control is toggled to True/False each time the control is clicked. Then the checkmark next to the menu control Use Splitter Tracker is toggled to indicate that the control is on or off. When the toolbar or status bar is hidden/unhidden, the DockingPane control needs to get the new dimensions of the window and resize the docking panes to fit in the new area that was freed up or removed from the form. To do this, call the RecalLayout method each time the status bar or toolbar is hidden/unhidden. Edit the mnuViewStatusBar and mnuViewToolbar Click event procedures the same way you edited the mnuPane event procedures. Add the code DockingPaneManager.RecalLayout to the end of each event procedure as in the following code
Private Sub mnuViewStatusBar_Click() mnuViewStatusBar.Checked = Not mnuViewStatusBar.Checked sbStatusBar.Visible = mnuViewStatusBar.Checked DockingPaneManager.RecalcLayout End Sub Private Sub mnuViewToolbar_Click() mnuViewToolbar.Checked = Not mnuViewToolbar.Checked tbToolBar.Visible = mnuViewToolbar.Checked DockingPaneManager.RecalcLayout End Sub

You have now completed this tutorial! If you are unclear on anything covered, you might want to go back and complete this tutorial again. It might be a good idea to add some additional functionality to this sample application to make sure you fully understand what is going on.