Access Cookbook - Ken Getz [99]
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")
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: