Copyright (c) Hyperion Entertainment and contributors.

Difference between revisions of "GadTools Library"

From AmigaOS Documentation Wiki
Jump to navigation Jump to search
 
(3 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
== GadTools Library ==
  
== GadTools Library ==
   
−
GadTools is designed to simplify the task of creating user interfaces with Intuition. GadTools offers a flexible and varied selection of gadgets and menus to help programmers through what used to be a difficult chore.
 +
Originally, programming even straightforward user interfaces in [[Intuition_Library|Intuition]] could be rather complicated, and certainly difficult for first-time programmers. The GadTools toolkit was introduced in AmigaOS 2.x to simplify the task. It provided relatively easy-to-use, higher-level chunks to build [http://en.wikipedia.org/wiki/Graphical_user_interface GUIs] from, and to help programmers through what used to be a difficult chore.
   
  +
{{Note|title=Note|text=As of AmigaOS 4.1 Final Edition, GadTools is basically a legacy toolkit retained for compatibility. Due to its inherent limitations, using GadTools in modern applications can no longer be recommended. Prefer using the object-oriented GUI programming framework based on [[BOOPSI]].}}
−
Intuition, the Amiga's graphical user interface, is a powerful and flexible environment. It allows a software designer a great degree of flexibility in creating dynamic and powerful user interfaces. However, the drawback of this flexibility is that programming even straightforward user interfaces can be complicated, and certainly difficult for first-time Intuition programmers.
  
−  
−
What the Gadget Toolkit (GadTools) attempts to do is harness the power of Intuition by providing easy-to-use, high-level chunks of user interface. GadTools doesn't pretend to answer all possible user interface needs of every application but by meeting the user interface needs of most applications, GadTools greatly simplifies the problem of designing user-friendly software on the Amiga.
  
−  
−
For applications with special needs, custom solutions can be created with Intuition's already-familiar gadgets or its new BOOPSI object-oriented custom gadget system; GadTools is compatible with these.
  
   
 
== Elements of GadTools ==
  
== Elements of GadTools ==
Line 17: Line 13:
 
GadTools provides a significant degree of visual consistency across multiple applications that use it. There is also internal consistency between different elements of GadTools; the look is clean and orderly. Depth is used not just for visual embellishment, but as an important cue. For instance, the user is free to select symbols that appear inside a "raised" area, but "recessed" areas are informational only, and clicking in them has no effect.
  
GadTools provides a significant degree of visual consistency across multiple applications that use it. There is also internal consistency between different elements of GadTools; the look is clean and orderly. Depth is used not just for visual embellishment, but as an important cue. For instance, the user is free to select symbols that appear inside a "raised" area, but "recessed" areas are informational only, and clicking in them has no effect.
   
−
GadTools is not amenable to creative post-processing or hacking by programmers looking to achieve a result other than what GadTools currently offers. Software developers whose needs extend beyond the standard features of GadTools should create custom gadgets that share the look and feel of GadTools by using either BOOPSI or by directly programming gadgets at a lower level. See [[Intuition_Gadgets|Intuition Gadgets]] and [[BOOPSI_-_Object_Oriented_Intuition|BOOPSI]] for more information. Follow the GadTools rules. Only in this way may GadTools grow and improve without hindrance, even allowing new features to automatically appear in future software when reasonable.
 +
GadTools is not amenable to creative post-processing or hacking by programmers looking to achieve a result other than what GadTools currently offers. Software developers whose needs extend beyond the standard features of GadTools should create custom gadgets that share the look and feel of GadTools by using either BOOPSI or by directly programming gadgets at a lower level. See [[Intuition_Gadgets|Intuition Gadgets]] and [[BOOPSI_-_Object_Oriented_Intuition|BOOPSI]] for more information.
   
 
=== GadTools Tags ===
  
=== GadTools Tags ===
Line 41: Line 37:
 
== Function Reference ==
  
== Function Reference ==
   
−
The following are brief descriptions of the Intuition functions discussed in this chapter. See the SDK for details on each function call.
 +
The following are brief descriptions of the Intuition functions discussed in this article. See the SDK for details on each function call.
   
 
{| class="wikitable"
  
{| class="wikitable"
Line 47: Line 43:
 
! Description
  
! Description
 
|-
  
|-
−
| CreateGadgetA()
 +
| CreateGadgetA()<br/>CreateGadget()
−
| Allocate GadTools gadget, tag array form.
 +
| Allocate GadTools gadget.
−
|-
  
−
| CreateGadget()
  
−
| Allocate GadTools gadget, varargs form.
  
 
|-
  
|-
 
| FreeGadgets()
  
| FreeGadgets()
 
| Free all GadTools gadgets.
  
| Free all GadTools gadgets.
 
|-
  
|-
−
| GT_SetGadgetAttrsA()
 +
| GT_SetGadgetAttrsA()<br/>GT_SetGadgetAttrs()
−
| Update gadget, tag array form.
 +
| Update gadget.
−
|-
  
−
| GT_SetGadgetAttrs()
  
−
| Update gadget, varargs form.
  
 
|-
  
|-
 
| CreateContext()
  
| CreateContext()
 
| Create a base for adding GadTools gadgets.
  
| Create a base for adding GadTools gadgets.
 
|-
  
|-
−
| CreateMenusA()
 +
| CreateMenusA()<br/>CreateMenus()
−
| Allocate GadTools menu structures, tag array form.
 +
| Allocate GadTools menu structures.
−
|-
  
−
| CreateMenus()
  
−
| Allocate GadTools menu structures, varargs form.
  
 
|-
  
|-
 
| FreeMenus()
  
| FreeMenus()
 
| Free menus allocated with CreateMenus().
  
| Free menus allocated with CreateMenus().
 
|-
  
|-
−
| LayoutMenuItemsA()
 +
| LayoutMenuItemsA()<br/>LayoutMenuItems()
−
| Format GadTools menu items, tag array form.
 +
| Format GadTools menu items.
−
|-
  
−
| LayoutMenuItems()
  
−
| Format GadTools menu items, varargs form.
  
−
|-
  
−
| LayoutMenusA()
  
−
| Format GadTools menus, tag array form.
  
 
|-
  
|-
−
| LayoutMenus()
 +
| LayoutMenusA()<br/>LayoutMenus()
−
| Format GadTools menus, varargs form.
 +
| Format GadTools menus.
 
|-
  
|-
 
| GT_GetIMsg()
  
| GT_GetIMsg()
Line 107: Line 88:
 
| GadTools gadget compatible version of EndRefresh().
  
| GadTools gadget compatible version of EndRefresh().
 
|-
  
|-
−
| DrawBevelBoxA()
 +
| DrawBevelBoxA()<br/>DrawBevelBox()
−
| Draw a 3D box, tag array form.
 +
| Draw a 3D box.
−
|-
  
−
| DrawBevelBox()
  
−
| Draw a 3D box, varargs form.
  
−
|-
  
−
| GetVisualInfoA()
  
−
| Get drawing information for GadTools, tag array form.
  
 
|-
  
|-
−
| GetVisualInfo()
 +
| GetVisualInfoA()<br/>GetVisualInfo()
−
| Get drawing information for GadTools, varargs form.
 +
| Get drawing information for GadTools.
 
|-
  
|-
 
| FreeVisualInfo()
  
| FreeVisualInfo()

Latest revision as of 21:43, 3 November 2015

GadTools Library

Originally, programming even straightforward user interfaces in Intuition could be rather complicated, and certainly difficult for first-time programmers. The GadTools toolkit was introduced in AmigaOS 2.x to simplify the task. It provided relatively easy-to-use, higher-level chunks to build GUIs from, and to help programmers through what used to be a difficult chore.

Note
As of AmigaOS 4.1 Final Edition, GadTools is basically a legacy toolkit retained for compatibility. Due to its inherent limitations, using GadTools in modern applications can no longer be recommended. Prefer using the object-oriented GUI programming framework based on BOOPSI.

Elements of GadTools

GadTools is the easy way to program gadgets and menus. With GadTools, the system handles the detail work required to control gadgets and menus so the application uses less code and simpler data structures.

Another key benefit of GadTools is its standardized and elegant look. All applications that use GadTools will share a similar appearance and behavior. Users will appreciate a sense of instant familiarity even the first time they use a product.

GadTools provides a significant degree of visual consistency across multiple applications that use it. There is also internal consistency between different elements of GadTools; the look is clean and orderly. Depth is used not just for visual embellishment, but as an important cue. For instance, the user is free to select symbols that appear inside a "raised" area, but "recessed" areas are informational only, and clicking in them has no effect.

GadTools is not amenable to creative post-processing or hacking by programmers looking to achieve a result other than what GadTools currently offers. Software developers whose needs extend beyond the standard features of GadTools should create custom gadgets that share the look and feel of GadTools by using either BOOPSI or by directly programming gadgets at a lower level. See Intuition Gadgets and BOOPSI for more information.

GadTools Tags

Many of the GadTools functions use TagItem arrays or tag lists to pass information across the function interface. These tag-based functions come in two types, one that takes a pointer to an array of tag items and one that takes a variable number of tag item arguments directly in the function call. In general, the second form, often called the varargs form because the call takes a variable number of arguments, is provided for convenience and is internally converted to the first form. When looking through the Autodocs or other Amiga reference material, the documentation for both forms is usually available in the array-based function description.

All GadTools tags begin with a leading "GT". In general, they also have a two-letter mnemonic for the kind of gadget in question. For example, slider gadgets recognize tags such as "GTSL_Level". The GadTools tags are defined in <libraries/gadtools.h>. Certain GadTools gadgets also recognize other Intuition tags such as GA_Disabled and PGA_Freedom, which can be found in <intuition/gadgetclass.h>.

For more information on tags and tag-based functions, be sure to see the Utility Library.

GadTools Menus

GadTools menus are the preferred way to manage menus on AmigaOS.

See GadTools Menus for more information on how to use them.

GadTools Gadgets

GadTools gadgets are largely superseded by BOOPSI-based GUI systems are to be avoided.

See GadTools Gadgets for more information about this obsolete GUI system.

Function Reference

The following are brief descriptions of the Intuition functions discussed in this article. See the SDK for details on each function call.

Function Description
CreateGadgetA()
CreateGadget() 		Allocate GadTools gadget.
FreeGadgets() Free all GadTools gadgets.
GT_SetGadgetAttrsA()
GT_SetGadgetAttrs() 		Update gadget.
CreateContext() Create a base for adding GadTools gadgets.
CreateMenusA()
CreateMenus() 		Allocate GadTools menu structures.
FreeMenus() Free menus allocated with CreateMenus().
LayoutMenuItemsA()
LayoutMenuItems() 		Format GadTools menu items.
LayoutMenusA()
LayoutMenus() 		Format GadTools menus.
GT_GetIMsg() GadTools gadget compatible version of GetMsg().
GT_ReplyIMsg() GadTools gadget compatible version of ReplyMsg().
GT_FilterIMsg() Process GadTools gadgets with GetMsg()/ReplyMsg().
GT_PostFilterIMsg() Process GadTools gadgets with GetMsg()/ReplyMsg().
GT_RefreshWindow() Display GadTools gadget imagery after creation.
GT_BeginRefresh() GadTools gadget compatible version of BeginRefresh().
GT_EndRefresh() GadTools gadget compatible version of EndRefresh().
DrawBevelBoxA()
DrawBevelBox() 		Draw a 3D box.
GetVisualInfoA()
GetVisualInfo() 		Get drawing information for GadTools.
FreeVisualInfo() Free drawing information for GadTools.
Retrieved from "http://wiki.amigaos.net/w/index.php?title=GadTools_Library&oldid=8272"