Contents
		License &Copyright
		Introduction
		Features
		Support
		Installation
		Adding a Tearoff to your Application
		Using Tearoff when your Application is running
		Options for the Tearoff template : Frame
		Options for the Tearoff template : Toolbox
		Advanced: View Toolbox Menu Item
		Examples
		Tips & FAQ
		Version History

License & Copyright

This template is copyright © 2009 by CapeSoft Software (Pty) Ltd.  None of the included files may be distributed. Your programs which use Tearoff can be distributed without any Tearoff royalties.

Each developer needs his own license to use Tearoff. (Need to buy more licenses?)

This product is provided as-is. Use it entirely at your own risk. Use of this product implies your acceptance of this, along with the recognition of copyright stated above. In no way will CapeSoft Software (Pty) Ltd, their employees or affiliates be liable in any way for any damages or business losses you may incur as a direct or indirect result of using this product.

Introduction

Derek kept moaning about a feature he saw on an Apple Mac 15 years ago. In those days you were able to 'tear off' a menu item and add it to a hot list. This was useful when you had a handful of menu items you often called, but which were scattered and buried all over the place. We couldn't add this feature to existing Windows programs, but at least it's now available in his, and our, past, current and future Clarion applications.

One good thing leads to another, and after using it in-house for a couple of months we've refined the idea a bit, and added a couple of minor features.

The challenge was to make it trivial to implement (it takes about 30 seconds), and easy to use - and we think we succeeded on both counts.

It's a simple feature - but try it in a program you actually use, it really does save a lot of effort...

Features

• Simple to add to your program (literally takes 30 seconds or less)
  
• User holds down the Control Key and Clicks a menu item. That item is added as a button to the Tearoff toolbox. Right-click the button to remove it from the toolbox.
  
• Tearoff Toolbox window is Dockable (C5 and later)
  
• All Tearoff settings are persistent from one session to the next
  
• Full support for Icons (even in C4). Takes the icons from the menu item (only in C5 or later) and also allows you to set icons for each menu item which display on the button, but not the menu item (all versions).
  
• Allows you to set button tips for the menu items, or uses the MSG attribute, or uses the button text.
  
• User has control over button width, and the format of the button (view text only, icon only or both).
  

Support

Your questions, comments and suggestions are welcome. Check our web page ( www.capesoft.com) for new versions. You can also contact us in one of the following ways.

CapeSoft Support
	Email	support@capesoft.com
	Telephone	+27 21 715 4000
	Fax	+27 21 715 2535
	Post	PO Box 511, Plumstead, 7801, Cape Town, South Africa

Tearoff is available for purchase at $49 from:

CapeSoft Sales
	Web	www.capesoft.com
	Email
	Telephone	+27 21 715 4000
	Fax	+27 21 715 2535
	Post	PO Box 511, Plumstead,7801, Cape Town, South Africa

Buy Online
	Web	www.clarionshop.com

Installation

1. Run the supplied installation file.

Adding a Tearoff to your Application

Adding a Tearoff to your Application is easy.

1.	While the App is Open go to the Application menu and select the Template Utility option.
2.	If your App is an ABC app then select the Import Tearoff Toolbox ABC item in the Tearoff class. If the App is based on the Clarion (Legacy) template set then select the Import Tearoff Toolbox Legacy item. This adds a Window procedure called TearoffToolBox to your application.
3.	Open the Frame Procedure.
4.	Go to the Extensions. Click on Insert.
5.	Select Activate CapeSoft Tearoff from the Class Tearoff. The default options are fine, read the next section for possible options.
6.	Close and save the window.

Using Tearoff when your application is running

We hope we've made this just as easy as the previous section.

1.	To Add a menu item to the Tearoff simply hold down the Control Key on the keyboard and Left Click the mouse on the required menu item. Note at this point you cannot add 'Std' items - i.e. menu items which make use of 'Std' behavior - for example the Print Setup item. Also you cannot add Menus themselves - only menu items.
2.	To Remove a menu item from the Tearoff simply Right-Click on that item in the Tearoff and select Delete.
3.	To Use an item in the Tearoff simply Left-Click on the item in the Tearoff.

Options for the Tearoff Template : Frame

General Tab

• Tearoff Toolbox Procedure : This defaults to TearoffToolBox, which is perfectly ok, but you can rename it if you want to. Actually the best way to rename the parameter is not to change it here, but rather Right-Click on the procedure in the IDE tree, and choose Rename.
  
• View Menu Item : One of the obvious features we added was the ability to link a menu item (typically something like View Toolbox) to the window so that the user can open and close it. this is discussed more completely in the section entitled Advanced :View Toolbox Menu Item.
  
• INI File Name : The entries in the Tearoff are stored in an INI file. By default this file is called by the same name as your application, and is stored in the windows directory. However you can specify the location, and name, of the ini file here.
  
• INI File Name is a variable. : Check this if you want to use a variable to contain the INIFile name.
  
• Maximum Tearoffs Allowed : By default you are allowed up to 20 items in the tearoff. However you can reduce this if you like - simply adjust the number here.
  
• Additional Button Settings : These allow you to set additional settings for each menu item. For example you can set an Icon for the menu item, even if you're using C4. This allows you to set an icon for the menu item, but not actually have the icon on the menu itself. If the menu item has an Icon anyway then you can override that icon here. (Useful if you've made your menu icons very small).  You can also override the Tip here. By default the tip is taken from the MSG attribute, or if that is blank, then from the menu text. NEW You can now override the Text for the button here as well.
  
• Disable Tearoff

Translate Tab

• Hint Message : If the user clicks on the View Menu item, and there are no items in the toolbox, then a message will appear with a Hint. Enter the hint's message here. Use quotes for an absolute value, or use a variable name (without an Exclamation mark).
  
• Heading : Enter the Heading for the Hint Message window here.
  
• Delete Items Message : If between program versions, items are added to the menu, then this could potentially lead to TearOff activating the incorrect menu item when the user clicks on it. This means that the menu needs to be deleted and repopulated. The user is first warned of these deletions before the toolbox items are deleted.
  
• Delete Items Heading : Enter the Heading for the Hint Message window here.

Advanced Tab

• Disable Tear Off : Click this on and no Tearoff code will be generated in the frame. This is useful during debugging if you suspect Tearoff is causing a problem in your application.
  
• Don't Strip '&' chars from text : By default HotKey markings will not be included on the text for the button. You can override this removal by clicking on the option here.
  
• Code to get Username : If you want Multiple Users to share the same INI file, then Tearoff needs a way of keeping the information for each user separate. It does this by making use of a UserName. Tearoff needs to know how to get the UserName. Enter the code here. [For Secwin use ds_CurrentLogin(AppNum) ]
  
• To Activate User must Hold Down : Select the keys that the user must hold down in order to make an item appear on the Tearoff Toolbox. For example, the Default is just Ctrl, so if the user holds down Ctrl while clicking then the item is added. However you might want to make it Ctrl-Alt or Alt-Shift or something like that.
  
• Event on Startup : TearOff uses an Event to trigger the toolbox window. If the default event number (731) clashes with an event in your application then you can set it to something else here.
  
• Check for new menu layout on startup : If this is on then the app will check the number of items in your menu when the program starts. If this number is different to the number last time the program ran, then a message will appear and the toolbox will be deleted. This feature prevents toolboxes and menu equate numbers from getting out of sync.

Options for the Tearoff Template : Toolbox

General Tab

• INI File Name. : The position of the Tearoff window is stored in an INI file. By default this file is called by the same name as your application, and is stored in the windows directory. However you can specify the location, and name, of the ini file here.
• INI File Name is a variable. : Check this if you want to use a variable to contain the INIFile name.
• Text Only Button Height : This setting will be used to set the height of the button, if the icon is not being displayed. A typical value is around 13.
• Text Button Width : This is the default setting for the text part of the button width. The user is able to resize the window which will adjust this setting. A good setting for this is between 80 and 110 depending on the length of your menu items.
• Icon Button Height : This setting will be used to set the height of the button, if the icon is being displayed. A typical value is around 21.
• Icon Button Width : This is the default setting for the icon part of the button width. Normally icons are square so this should be near the Icon Button Height (around 21).
• Disable Tear Off : Click this on and no Tearoff code will be generated in the toolbox procedure. This is useful during debugging if you suspect Tearoff is causing a problem in your application.
• Initial Position : Select the default position for the first time that the user uses the Tearoff menu. This allows you to specify that the window starts out life docked, or floating.

Translate Tab

• Translate Tab : When a user Right-Clicks on one of the buttons in the Tear-Off menu, then a popup menu appears. You can set the text for the popup here.

Advanced Tab

• Always Left Justify Button Text : By default the text will be center justified if the icon is not displayed. However in some cases it looks better if the text is Left Justified. You decide....

Advanced: View Toolbox Menu item

Tearoff includes support for a View ToolBox menu item. This is typically a Check Menu Item added to your View menu which allows the user to turn the Toolbox on and off. To add this feature to your application you must;

1.	Open the Frame Procedure.
2.	Go to the Window Editor - to the Menu Editor. Add a new menu item. (Typically in the View menu, View Toolbox). Click on Toggle (on/off) Item. Set the Use Variable to be Tear:View
3.	Go to the Extensions for the Frame, to the Activate CapeSoft Tearoff extension, set the 'View' menu item option to be ?Tear:View
4.	Close and save the window.

Examples

There is an example in your \Clarion5\3rdParty\Examples\Tearoff\Abc directory and in the \Clarion5\3rdParty\Examples\Tearoff\Legacy directory.

Tips & FAQ

Clarion Versions : Tearoff is available for Clarion 5, 5.5 and 6.  There is no upgrade charge. However you will need the correct version to match the version of Clarion that you are using. Download the correct version from www.capesoft.com .

Compile Error : Unknown Identifier ?Panel1 : You'll get this in Clarion 4 when upgrading from an earlier version of Tearoff. Simply re-import the window from the TXA again. See Adding Tearoff to your application. 

Ezhelp: If you have Ezhelp loaded in the same application, then you'll want to disable Ezhelp on the Tearoff window. To do this simply go to the Ezhelp extension on the window, and click on the option "disable Ezhelp in this procedure".

Tearoff Toolbox "look" : Remember the Tearoff toolbox procedure is a normal Clarion window, with normal Clarion buttons. So you can set the font, and button style to match the rest of your app.  Makeover 2.0 and later also supports a "Toolbox" style.

INI file location : By default the Tearoff settings are stored in an INI file in the Windows directory. This allows users on different machines to have different Tearoff menus. However you can force the INI file into the 'current' directory by prepending its name with .\    This allows you to allow 1 user to access the program from various workstations, yet keep his own Tearoff settings.  (See next tip). Alternatively it allows users to share a common Tearoff menu. Normally you would want your TearOff toolbox settings and your TearOff menu settings stored in the same ini file. You need to make sure that the same ini file is used in both the TearOff extension template on the frame as well as in the TearOff controls toolbox window. You can use a variable to contain the ini filename - check the INI Filename is a variable checkbox on both of the TearOff Control templates that appear on the TearOffToolBox and your Frame.

Multi-User : Some users have expressed a desire to share the settings, for multiple users, in the same ini file but with each user still having their own Tearoff settings. This is now supported. Simply make sure you have a variable, in the frame, that contains the current user's login ID. For example, using Secwin, this ID would be got using the ds_CurrentLogin function.

Long Menu Text : In some programs the menu items are generally very long. In this case it's not a bad idea to set the Text Only Button Height option on the Tearoff window extension options to a value which allows 2 lines of text (set it to say 20). Although this makes the toolbar higher, and hence uses up some more screen space, it allows for narrower, and hence more, buttons on the bar.

Disabling TearOff at runtime: The easiest way to disable Tearoff at runtime, is to place a return in the ThisWindow.Init method of the TearOffToolbox window. For example:

If GLO:DisableTearOff = 1 then
  return level:notify
end