Implementing a Templates Menu by Seth Willits 10-15-03 Printer Version

In this tutorial we're going to learn of one specific use for subclassing the MenuItem class. What we'll be doing is creating a Templates menu which has a menu item for each of the files in the application's "Templates" folder. When the menu item is selected, the application will create a new untitled document window and display the contents of the template file.

About The MenuItem Class
Every menu and menu item, or submenu item, and even subsubmenu items, are all of the class "MenuItem". Typically we make a distinction between "menus" and "menu items," but in reality, everything in and attached to the menu bar is a menu item. Our regular "menus" such as File or Edit, are actually menu items with submenu items (New, Open, Save, Quit). For example, take the "Open Recent" menu item in the "File" menu in REALbasic and assume that we recently opened a project named "Project.rb" so it appears as a menu item in the "Open Recent" menu. "Project.rb" is a submenu item of the "Open Recent" menu item, and "Open Recent" is a submenu item of the "File" menu item. File in turn is then a menu item of the menu bar, or the MenuBar class. We won't get into the MenuBar class in this tutorial, but realize that everything within the menu bar is simply a tree of connected menu items associated with the menu bar.

MenuItem is a class which represents a menu item. Properties of the MenuItem class include the name of the menu item, the style (bold, italic, underline), the keyboard shortcut, and a boolean for whether or not the menu item has a sub menu. Menu items directly in the menu bar (aka, "menus"), must have sub menus, cannot have any styles, and cannot have a keyboard shortcut. Although "menus" are treated a little differently from "menu items", they are all still instances of the MenuItem class.

The Implementation
In our project, we're going to create a subclass of the MenuItem class which will represent a menuitem in the "Templates" menu in our application. To start, make a new project and rename the window in your project to "Document", create an editfield inside the window, resize it to be the same size of the window, multiline, and name it "TextField". Next, create a new menu named "Templates" in the menubar, and then lastly create a new "MenuItem" subclass called "TemplateItem".

After this, we'll implement the TemplateItem class. We're first going to want to create a new property, "File as FolderItem". The File property will be the folderitem pointing to the file which the menu item represents. When the menu item is selected, the application will use the File property to know which template to open.

The EnableMenu event of the MenuItem class is just like the EnableMenuItems event. Whenever the menu bar items need to be enabled or disabled, first the EnableMenu events of all of the MenuItems in the menu bar are called, then then EnableMenuItems event of any controls in the window, next is the EnableMenuItems event of the window, and finally the EnableMenuItems event of the application class instance. In our case, the menu items in the Templates menu are always going to be enabled so we simply write "me.enable" in the event.

The Action event of the MenuItem is the Menu Handler for that menu item. It behaves in the same manner as the Menu Handlers in other classes and windows. When a template menu item is selected the Action event of the TemplateItem class is fired and in response, we're going to open the template, create a new document window, and set the text of the editfield in the window to be the text inside of the template file.

Function Action() As Boolean
  dim doc as Document
  dim tin as TextInputStream

  // Create window and open template
  tin = File.OpenAsTextFile
    if tin = nil then
  return false
  end if
  doc = New Document

  // Read file and show window
  doc.TextField.text = tin.ReadAll
  doc.Show

  // Close file
  tin.Close
End Function


Creating the MenuItems
We now have a self-contained MenuItem subclass which is responsible for enabling itself and handling when it is selected. The only thing now remaining is actually creating the menu items and putting them inside of the Templates menu which we'll do inside of our application class' EnableMenuItems event (App.EnableMenuItems). The reason I've chosen to use the EnableMenuItems event as opposed to the Open event, is because if we use the Open event, the menu items are only created one time. This means that if the user adds or deletes a file in the "Templates" folder, or even the whole folder itself, the application will still show the templates in the menu which will lead to problems when they try to open them. By using the EnableMenuItems event, we ensure that the menu and menu items are as up-to-date as can be.

Sub EnableMenuItems()
  dim templatesFolder, file as FolderItem
  dim template as TemplateItem
  dim index as integer
  
  
  // Remove existing items
  while TemplatesMenu.Count > 0
    TemplatesMenu.Remove 0
  wend
  
  // Find folder
  templatesFolder = GetFolderItem("Templates")
    
  // Only if the folder exists
  if templatesFolder.Exists then
    
    // Add each template to the menu
    for index = templatesFolder.Count DownTo 1
      file = templatesFolder.Item(index)
      if file <> nil and file.Visible = true and file.Directory = false then
        template = New TemplateItem
        template.Text = templatesFolder.Item(index).Name
        template.File = templatesFolder.Item(index)
        TemplatesMenu.Append template
      end if
    next
  end if
  
  
  // Hide the menu if no items are in it
  TemplatesMenu.Visible = TemplatesMenu.Count > 0
End Sub


As you can see from the code, what we do first is remove any existing items in the "Templates" menu since the EnableMenuItems event is called many many times and we need to remove the existing items so we don't add duplicates. Next we get the folderitem to the Templates folder. In the code above, the folder is named "Templates" and is in the same folder as the application. We then test to see if the folder exists. If it doesn't exist, then we know there obviously aren't any templates inside of it, so we just skip over the code which adds the menu items. If the folder does exist, we then loop through each folderitem inside of the templates folder. If the file is visible and not a folder, then we assume that files is a template. I emphasize assume because you should really do whatever kind of validation is necessary to make sure that the file is actually a document your application can open, but for the sake of simplicity, this tutorial simply assumes that any file in the folder is a template.

Once we determine that folderitem we have is a document template, we create a new instance of the TemplateItem class, set its caption to the name of the file, and set its File property to the folderitem of the template. The last step is to add the menu item to the "Templates" menu we created earlier. Now, remember that everything is a subclass of the menu item class. This applies to the "Templates" menu as well. If you'd like to verify it for yourself, look at the "Templates" menu in the Menu Editor and see that its super is "MenuItem". Also note that the name is "TemplatesMenu". With these two facts, we can call the "Append" method of TemplatesMenu, a MenuItem subclass, to add the given MenuItem instance to "Templates" menu. Side note: Using the Append method with any menu item will automatically set the "SubMenu" property of the item to true.

The very last step in the even is to hide the "Templates" menu if no menu items are inside of it. We do this because it's quite useless to display a "Templates" menu if there are no templates to display in it.

Our First Run
With that code written, compile and run the project. You should then happily get a menu named "Templates" which has exactly nothing in it. Why nothing? Because we didn't make a templates folder!

Find the project for the tutorial in Finder. Next, create a folder named "Templates" and drop a couple of text files into it. (Files are included in the project download for your convenience.) After doing so, return to REALbasic and run the project again.

Tada!

I hope this tutorial has been a help to you in some way.