Access Cookbook 2nd Edition-Access Cookbook 2nd Edition

Recipe 4.7 Change and Reset the Access Caption Bar

4.7.1 Problem

You'd like to be able to change the caption of the main Access window as part of your application. Of course, you need to be able to reset it back to its original value when you're done. You've found the AppTitle property in Access, but you just can't get it to work. Is there some simple way to retrieve and set the Access caption, as you can with any of the windows within Access?

4.7.2 Solution

This is one situation where it's simpler to use the Windows API than it is to use the built-in functionality. Although Access does support a property of the current database, AppTitle, that you can use to set and retrieve the Access titlebar, it's clumsy to use because AppTitle is a user-defined property. If the property doesn't yet exist in a database, you must create it. With the Windows API, retrieving and setting the Access caption both require just a few predictable steps, and neither process is terribly difficult. This solution demonstrates the steps to set and retrieve the Access caption with the Windows API. The AppTitle property is discussed in Recipe 4.7.3.

To try changing the Access caption, load and run frmSetTitleBarCaptionAPI from 04-07.MDB. The form displays the current Access caption. By filling in a new value in the New Access Caption text box and pressing the Set New Caption button, you can change the caption on the main Access window. Figure 4-14 shows the form once it's already done its work. Press the Reset Caption button when you're done to reset the Access caption.

Figure 4-14. frmSetTitleBarCaptionAPI after it has set the new Access caption

To include this functionality in your own applications, follow these steps:

Import the module basCaption (which supplies the necessary Windows API declarations and the interface routines) from 04-07.MDB.
To retrieve the current Access caption, call the acbGetAccessCaption function. For example:
```
strOldCaption = acbGetAccessCaption( )
```
To set a new Access caption, call the acbSetAccessCaption subroutine, passing to it a string that holds your new caption, as follows (by appending an empty string to the contents of the text box, you guarantee that the value you pass to acbSetAccessCaption is indeed a string, even if the text box's content is empty):
```
Call acbSetAccessCaption(Me.txtOldCaption & "")
```
To set the caption of any window given its window handle, call the SetWindowText API directly:
```
Call SetWindowText(hWnd, "Your New Caption")
```

4.7.3 Discussion

To retrieve the Access window caption, call the acbGetAccessCaption function, which passes the Access window handle (Application.hWndAccessApp) to the more generalized acbGetWindowCaption function, which does its work in the following three steps:

It uses the built-in Space function to size a string buffer large enough to hold all the characters.
It calls the Windows API function GetWindowText to fill the buffer with the actual window caption. GetWindowText returns the number of characters it filled in.
It uses the built-in Left function to remove extra characters.

The code for the acbGetWindowCaption function is as follows:

Private Function acbGetWindowCaption(ByVal hWnd As Long) As Variant

   ' Get any window's caption, given its hWnd.

   Dim intLen As Integer
   Dim strBuffer As String

   Const acbcMaxLen = 255

   If hWnd <> 0 Then
      strBuffer = Space(acbcMaxLen)
      intLen = GetWindowText(hWnd, strBuffer, acbcMaxLen)
      acbGetWindowCaption = Left(strBuffer, intLen)
   End If
End Function

To set the Access caption, call the acbSetAccessCaption subroutine, passing to it the new caption you'd like to use. This procedure is much simpler than the previous one: it passes the Access window handle and the caption to the SetWindowText API procedure. The code for the acbSetAccessCaption subroutine is as follows:

Public Sub acbSetAccessCaption(ByVal strCaption As String)
   
   ' Set the Access caption to be the value in strCaption.
   Call SetWindowText(Application.hWndAccessApp, strCaption)
End Sub

Access does provide a built-in mechanism for setting the caption to be used while a specific database is loaded: the Tools Startup dialog, shown in Figure 4-15. Using this dialog, you can set many of the startup options you'll need to deliver any application: the startup form, titlebar, icon, shortcut menu bar, and global menu bar. You can control other Access behavior as well, such as displaying the database window at startup, displaying the status bar, using built-in toolbars, or allowing toolbar changes.

Figure 4-15. Use the Tools Startup dialog to set application startup options

The AppTitle property allows you to set the database's titlebar, and the AppIcon property allows you to set an icon for the application. Both are usually set using the Startup dialog, but you can also modify them programmatically, as long as you remember that they're not built-in properties of the database. You must first create the properties and append them to the collection of properties; then you'll be able to use them.

The example database includes a form called frmSetTitleBarCaptionProperty that uses the AppTitle database property, creating the property on the fly if necessary. Here's the code that sets a new titlebar caption:

Private Sub cmdNewCaption_Click( )
    Dim prp As DAO.Property
    On Error GoTo HandleErr
    CurrentDb.Properties("AppTitle") = Me.txtNewCaption & ""
    
ExitHere:
    Application.RefreshTitleBar
    Exit Sub

HandleErr:
    Select Case Err.Number
        Case 3270 'Property not found
            Set prp = CurrentDb.CreateProperty( _
             "AppTitle", dbText, Me.txtNewCaption)
            CurrentDb.Properties.Append prp
        Case Else
            MsgBox _
             Err.Number & ": " & Err.Description, , "cmdNewCaption"
    End Select
    Resume ExitHere
End Sub

To retrieve the titlebar caption when the form opens, we used error handling that assumes the caption is "Microsoft Access" if the AppTitle property hasn't been used to change it:

Private Sub Form_Open(Cancel As Integer)
    On Error Resume Next
    Me.txtOldCaption = CurrentDb.Properties("AppTitle")
    If Err.Number <> 0 Then
        Me.txtOldCaption = "Microsoft Access"
    End If
End Sub

What are the trade-offs? The Windows API requires less code, runs faster, and works with applications other than Access (if you can get a window handle, you can set the caption). However, the AppTitle property actually persistently sets the database's property, so the next time you load the database, the title is set for you. It takes a bit more work to use the non-API Access method, but it does allow you to preserve the setting for your next session.

One final note: the Windows API allows you to set the caption to be an empty string. You cannot set the Access AppTitle property to be an empty string; Access will reject it. If you want to remove the text from the titlebar altogether, use the API method.

Create Your Own Splash Screen

The Tools Startup menu does not provide a method by which you can supply your own startup bitmap image. If you want to supply your own bitmap splash screen to use rather than Access's built-in image, you can place a bitmap (*.bmp) file in the same directory as your application with the same name as your application. When you double-click on your MDB file to start it, or create a shortcut that starts it, Access will find your bitmap and use it as your startup splash screen. If you want no splash screen at all, simply create a single-pixel bitmap (use a light color for that single pixel). It will be so small that no one will notice it as Access opens.

[ Team LiB ]