License & Copyright
This template is copyright © 2015 by CapeSoft
Software. 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, 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
- All Tearoff settings are persistent from one session to the next
- Full support for Icons. Takes the icons from the menu item 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 |
 |
| Telephone |
+27 87 828 0123
(087) 828 0123 |
Installation
1. Run the supplied installation file.
Adding Tearoff to your Application
Adding a Tearoff to your Application is easy.
| 1. |
Open the app and add the Global Extension, ActivateTearOff. |
| 2. |
On the Global Extension, click on the Import TearOff
Procedure button. |
| 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 6, 7, 8 and 9 There is no upgrade charge.
Download the latest 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
Download latest version
here
Version 2.08: 27 May 2025
Version 2.07: 25 June 2021
- Fix: Template generated the wrong control number when loading
- Change: TearQueue Name and Icon fields made bigger
Version 2.06: 24 June 2021
- Fix: Icons could get lost if tearoff was on toolbar button not menu
item.
- General: Template tidyup
Version 2.05: 25 May 2021
- Add: Clarion 11.1 to install.
Version 2.04: 18 Sept 2018
- Add: Clarion 11 to install.
Version 2.03: Released 28 May 2015
Version 2.02: Released 25 February 2015
- Clarion 10 build
- Removed calls to %cwversion
Version 2.01: Released 31 January 2014
Version 2.00: Released 12 September 2013
- Global Extension created.
- TearOff Extension added to frame automatically when Global Extension
added.
- "Tear Off Toolbox" procedure option moved from Frame template to
Global Extension.
Version 1.94: Released 1 May 2013
- Clarion 9 compatible build.
- Fix for Clarion 8 ABC classes - uses , method name instead of method
name in the where clause.
Version 1.93: Released May 2012
- Clarion 8 compatible build.
- Include version number in the global extension template list.
Version 1.92: Released February 2010
- Fixed bug with generating default icon over button icon
Version 1.91: Released November 10 2008
- Clarion 7 compatible install.
- INI Filename and section now uses quotes (so that a variable can be
used). Non-quoted constants are automatically upgraded to contain
quotes.
- Local disable tearoff in the template.
Version 1.90: Released June 12 2007
- Template Change - added support for a default icon.
Version 1.89: Released July 13 2007
- Added support for Makeover 2.76 (new syntax for .Refresh method)
Added embed point at top of StartTear routine
Version 1.87: Released 23 March 2007
- Added an option to suppress the check for new menu items on startup.
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
