License
& Copyright
This template is copyright © 2008 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.
| |
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:
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
Version
History
Version 1.90: Released June 12 2007
Version 1.89: Released July 13 2007
Version 1.87:
Released 23 March 2007
Version 1.86: Released 29 November 2006
- Docking (when default to blank) was not working correctly. Workaround for
blank docking saved - now uses Default docking position if blank in the ini
file.
Version 1.85: Released 21 July 2006
- Fix regression for Clarion5 legacy users (was using %DataSection to define
the TearOff local variables) and %Family was being defined too late.
Version 1.84: Released 23 June 2006
- Fix - allows variable INI filenames (Check the FAQs
for details.
Version 1.83: Released 19 June 2006
- Fix - themes docked buttons when docked top or bottom.
Version 1.82: Released 7 June 2006
- If Items in the menu are added, then TearOff could potentially not work
(select the wrong menu item). If the number of menu items changes, then the
TearOff box items are deleted and need to be repopulated. You can translate
the warning message in the TearOff Frame's extension template.
Version 1.81: Released 7 January 2005
- Support for Clarion 6.1
- Fix bug in 6.1 Legacy OPEN statement
Version 1.7: Released 25 March 2002
- Improved support for Makeover.
- Checks added to keep the TearOff window from having a negative position.
- In ABC suppresses the normal Window Restore features.
Version 1.6: Released 2 March 2001
- Support for Clarion 5.5a added
- Lets you choose the key combination needed to add an item to the toolbox
Version 1.55: Released 18 May 2000
Version 1.5: Released 20 March 2000
- Fixed bug : which limited buttons to 9 (not 20)
- Improvement : Allow button overrides for Text, Icons etc.
- Improvement : Developer decides if the buttons are ordered alphabetically
or not.
- Improvement : Assorted Embed points added for those hard-core coders amongst
us.
- Improvement : Removes HotKeys (&) from the button text.
- Improvement : Added Left Justify option to Control Template
- Improvement : Added Initial Position option to Control Template
- Improvement : Added Sort Alphabetically option to Frame Extension
- Improvement : Strips HotKeys (&) from Button Text
- Improvement : Allows INI file sharing via UserNames
- Improvement : Compatible with Makeover (for best results use Makeover 2
or later)
Version 1.1: Released December 24 1999
- Fixed Bug : 'Open window' in ABC moved closer to old 'Open Window'.
- Fixed Bug : Status of Toolbox window (open or closed) saved.
- Fixed Bug : Size of window correctly saved
- Fixed Bug : Using Makeover and Tearoff and ABC together fixed.
- Improvement : Increased maximum buttons from 9 to 20.
- Improvement : Much improved support for icons on the buttons (even in C4).
- Improvement : Button size saved.
- New Feature : Added Additional Button Settings to the Frame extension.
See Options for the Tearoff Template : Frame.
- New Feature : Added Button sizing features to Toolbox extension.
See Options for the Tearoff Template : Toolbox.
- New Feature : Button Tips added. You can set the tip on the Frame Extension
Additional Button Settings, if there's no tip there then the MSG attribute
from the menu item will be used. If that is blank then the text of the menu
item will be used.
Version 1.0: Released December 20 1999
[End of document]
