<li><p>Start Page- This property specifies which page <em>TQt Assistant</em> should initially display when the profile is used. Usually, this is the HTML file which contains the documentation's table of contents. This property also describes the default location to go to when pressing the home button in <em>TQt Assistant</em>'s main user interface. The start page is specified relative to the location of the profile. The property name is <tt>startpage</tt></p>
<li><p>About Menu Text- This property describes the text that appears in the <b>Help</b> menu, e.g. About Application. The property name is <tt>aboutmenutext</tt></p>
<li><p>About URL- This property can be used to point to an HTML file that describes the contents in the About dialog that is opened for the <b>Help</b> menu, e.g. About Application. The url is specified relative to the location of the profile. The property name is <tt>abouturl</tt></p>
<li><p><em>TQt Assistant</em> Documentation- This property describes the location of the <em>TQt Assistant</em> documentation. This is retquired since <em>TQt Assistant</em> provides self help, such as the full text search help and the <em>TQt Assistant</em> Manual option in the <b>Help</b> menu. The location is a directory relative to the location of the profile. The property name is <tt>assistantdocs</tt>.</p>
<li><p><em>TQt Assistant</em> Documentation- This property describes the location of the <em>TQt Assistant</em> documentation. This is required since <em>TQt Assistant</em> provides self help, such as the full text search help and the <em>TQt Assistant</em> Manual option in the <b>Help</b> menu. The location is a directory relative to the location of the profile. The property name is <tt>assistantdocs</tt>.</p>
</ul><p>To define a profile, one needs to specify a <em>TQt Assistant</em> Document Profile, usually abbreviated <tt>.adp</tt>. The profile is an extension of the Documentation Content File described above. We add a <tt>profile</tt> tag containing <tt>property</tt> tags to the format.</p>
<p>An example of a document profile file is shown below:</p>
<p>This manual presents <em>TQt Designer</em>, a tool for designing and implementing user interfaces built with the TQt multiplatform GUI toolkit. <em>TQt Designer</em> makes it easy to experiment with user interface design. At any time you can generate the code retquired to reproduce the user interface from the files <em>TQt Designer</em> produces, changing your design as often as you like. If you used an earlier version you will find yourself immediately productive in the new version since the interface is very similar. And you will also find new widgets and new and improved functionality which have been developed as a result of your feedback.</p>
<p>This manual presents <em>TQt Designer</em>, a tool for designing and implementing user interfaces built with the TQt multiplatform GUI toolkit. <em>TQt Designer</em> makes it easy to experiment with user interface design. At any time you can generate the code required to reproduce the user interface from the files <em>TQt Designer</em> produces, changing your design as often as you like. If you used an earlier version you will find yourself immediately productive in the new version since the interface is very similar. And you will also find new widgets and new and improved functionality which have been developed as a result of your feedback.</p>
<p><em>TQt Designer</em> helps you build user interfaces with layout tools that move and scale your widgets (<em>controls</em> in Windows terminology) automatically at runtime. The resulting interfaces are both functional and attractive, comfortably suiting your users' operating environments and preferences. <em>TQt Designer</em> supports TQt's signals and slots mechanism for type-safe communication between widgets. <em>TQt Designer</em> includes a code editor which you can use to embed your own custom slots inside the generated code. Those who prefer to separate generated code from hand crafted code can continue to use the subclassing approach pioneered in the first version of <em>TQt Designer</em>.<!-- index Controls!Widgets --></p>
<p>The manual introduces you to <em>TQt Designer</em> by leading you through the development of example applications. The first seven chapters are tutorials, each designed to be as self-contained as possible. Every chapter, except the first three, assumes that you are familiar with the material in chapters two and three which cover the basics of building a TQt application with <em>TQt Designer</em>. Here's a brief overview of the chapters:</p>
<ul><li><p>Chapter one, <ahref="designer-manual-2.html">Quick Start</a>, is a fast hands-on tutorial that takes you through the creation of a short, simple dialog application. The aim of this chapter is to give you a feel for how <em>TQt Designer</em> works, with explanations and details deferred to later chapters.</p>
<li><p>Chapter two, <ahref="designer-manual-3.html">Creating a Main Window Application</a>, introduces <em>TQt Designer</em> and takes you step by step through the creation of a small but fully functional application. Along the way you will learn how to create a main window with menus, toolbars and a status bar. Most of the application's implementation will be covered, but the custom dialogs are deferred until chapter three. In the course of this chapter you will use the form and property editors to customize the application. You'll also learn how to use TQt's signals and slots mechanism and <em>TQt Designer</em>'s built-in code editor to make the application functional. We will also explain how to use <tt>qmake</tt> to generate a Makefile so that you can compile and run the application.</p>
<li><p>In chapter three, <ahref="designer-manual-4.html">Creating Dialogs</a>, we will create the custom dialogs retquired by the main window application created in chapter two. In addition to demonstrating various ways of creating dialogs, you will also learn how to lay out forms using the layout tools.</p>
<li><p>In chapter three, <ahref="designer-manual-4.html">Creating Dialogs</a>, we will create the custom dialogs required by the main window application created in chapter two. In addition to demonstrating various ways of creating dialogs, you will also learn how to lay out forms using the layout tools.</p>
<li><p>Chapter four, <ahref="designer-manual-5.html#the-designer-approach">The Designer Approach</a>, provides information on the <em>TQt Designer</em> approach to developing applications, and explains some of the rationale behind <em>TQt Designer</em>.</p>
<li><p>Chapter five, <ahref="designer-manual-6.html">Subclassing and Dynamic Dialogs</a>, will show you how to subclass a form; this allows you to clearly separate the user interface from the underlying code that implements its functionality. Additional information on <tt>qmake</tt> and <tt>uic</tt> is included in this chapter. This chapter will also explain how you can dynamically load dialogs from<!-- index .ui --><tt>.ui</tt> files into your application using <ahref="qwidgetfactory.html">TQWidgetFactory</a> and how to access the widgets and sub-widgets of these dialogs.</p>
<li><p>Chapter six, <ahref="designer-manual-7.html">Creating Custom Widgets</a>, explains how you can create your own custom widgets. Both the simple method, that was introduced with the first version of <em>TQt Designer</em>, and the new more powerful method using plugins, are explained.</p>
</ul><p>The remaining chapters provide reference material that explains <em>TQt Designer</em>'s <ahref="designer-manual-11.html#reference-menu-options">menu options</a>, <ahref="designer-manual-12.html#reference-toolbar-buttons">toolbars</a>, <ahref="designer-manual-10.html#reference-key-bindings">key bindings</a>, <ahref="designer-manual-13.html#reference-dialogs">dialogs</a>, <ahref="designer-manual-14.html#reference-wizards">wizards</a>, and <ahref="designer-manual-15.html#reference-windows">windows</a> in detail.</p>
<h3><aname="2"></a>What You Should Know</h3>
<p>This manual assumes that you have some basic knowledge of C++ and the TQt GUI toolkit. If you need to learn more about C++ or TQt there are a vast number of C++ books available, and a small but increasing number of TQt books. TQt comes with extensive online documentation and many example applications that you can try.</p>
<p>The Enterprise Edition of TQt includes the TQt SQL module. In <ahref="designer-manual-8.html">Creating Database Applications</a> we demonstrate how to build SQL applications with <em>TQt Designer</em>; this chapter retquires some knowledge of SQL and relational databases.</p>
<p>The Enterprise Edition of TQt includes the TQt SQL module. In <ahref="designer-manual-8.html">Creating Database Applications</a> we demonstrate how to build SQL applications with <em>TQt Designer</em>; this chapter requires some knowledge of SQL and relational databases.</p>
<h3><aname="3"></a>What's New in <em>TQt Designer</em> for TQt 3.0?</h3>
<p>This version of <em>TQt Designer</em> has a great deal more functionality than its predecessor. For example, the code for custom slots can be edited directly in <em>TQt Designer</em>; main windows with actions, toolbars and menus can be created; layouts that incorporate splitters can be used; and plugins allow you to package any number of custom widgets and make them available to <em>TQt Designer</em>. Many other enhancements have been incorporated, from small improvements in the user interface to improved efficiency, for example the ability to share pixmaps across all the forms in an application.</p>
<p>This version of <em>TQt Designer</em> introduces project files which make it easy to switch between all the forms in an application, and to maintain a common set of database settings and images. Although subclassing is fully supported, writing code directly in <em>TQt Designer</em> offers a number of benefits which are covered in <ahref="designer-manual-5.html#the-designer-approach">The Designer Approach</a> chapter. A new library, <tt>libtqui</tt>, has also been introduced which allows you to load dialogs dynamically at runtime from <em>TQt Designer</em>'s <tt>.ui</tt> files. This allows you to provide your application's users with considerable interface customizability without them needing to use C++.</p>
<p>Click <b>Edit|Slots</b> to invoke the <em>Edit Functions</em> dialog. Use this dialog to edit or create slots and functions which are used in conjunction with signals to provide communication between objects.</p>
<p>When this dialog is invoked, all existing slots and functions are shown in the listview. The column headers Function, Return Type, Specifier, Access, Type, and In Use provide details about each function that is listed. Click on any of the column headers to sort the functions. To create a new function, click the <b>New Function</b> button. The new function has a default name that you should replace by typing the new name in the 'Function' line edit. The 'Return Type' is also a default that can be changed by typing in the line edit. To change the 'Specifier' or 'Access', click the combobox and choose the retquired specifier or access. To change the type of a function (function or slot), click the Type combobox. To remove a function, click the function you want to delete, and then click the <b>Delete Function</b> button.</p>
<p>When this dialog is invoked, all existing slots and functions are shown in the listview. The column headers Function, Return Type, Specifier, Access, Type, and In Use provide details about each function that is listed. Click on any of the column headers to sort the functions. To create a new function, click the <b>New Function</b> button. The new function has a default name that you should replace by typing the new name in the 'Function' line edit. The 'Return Type' is also a default that can be changed by typing in the line edit. To change the 'Specifier' or 'Access', click the combobox and choose the required specifier or access. To change the type of a function (function or slot), click the Type combobox. To remove a function, click the function you want to delete, and then click the <b>Delete Function</b> button.</p>
<p>Click <b>OK</b> to save all changes made to the functions. Click <b>Cancel</b> to leave the dialog without making any changes to the functions.</p>
<aname="dialog-view-connections"></a><h4><aname="4-2"></a>View and Edit Connections Dialog</h4>
<p>Click <b>Edit|Form Settings</b> to invoke the <em>Form Settings</em> dialog. Use this dialog to save the form's settings, pixmap, and layout properties.</p>
<h5><aname="4-3-1"></a>Settings</h5>
<p>In the Settings section, you can change or add the name of the class that will be created by typing in the 'Class Name' line edit. Note that the default name is the form name, but it can be changed. You can also enter text to the 'Comment' and 'Author' line edits or leave them blank, since they are not retquired.</p>
<p>In the Settings section, you can change or add the name of the class that will be created by typing in the 'Class Name' line edit. Note that the default name is the form name, but it can be changed. You can also enter text to the 'Comment' and 'Author' line edits or leave them blank, since they are not required.</p>
<h5><aname="4-3-2"></a>Pixmaps</h5>
<p>The default (for projects) is 'Project Imagefile'. This is the recommended option. Images are handled automatically, with <em>TQt Designer</em> storing the images in a subdirectory, and <tt>uic</tt> producing code that contains the images and the necessary supporting code. Each image is stored just once, no matter how many forms it is used in.</p>
<p>If you do not want <em>TQt Designer</em> to handle the images, (or are not using a project) choose either 'Save Inline' or 'Use Function'. 'Save Inline' saves the pixmaps in the <tt>.ui</tt> files. The disadvantage of this approach is that it stores images in the forms in which they're used, meaning that images cannot be shared across forms. Click 'Use Function' to use your own icon-loader function for loading pixmaps. Type the function's name (with no signature) in the 'Use Function' line edit. This function will be used in the generated code for loading pixmaps. Your function will be called with the text you put in the pixmap property (e.g. the image name) whenever an image is retquired.</p>
<p>If you do not want <em>TQt Designer</em> to handle the images, (or are not using a project) choose either 'Save Inline' or 'Use Function'. 'Save Inline' saves the pixmaps in the <tt>.ui</tt> files. The disadvantage of this approach is that it stores images in the forms in which they're used, meaning that images cannot be shared across forms. Click 'Use Function' to use your own icon-loader function for loading pixmaps. Type the function's name (with no signature) in the 'Use Function' line edit. This function will be used in the generated code for loading pixmaps. Your function will be called with the text you put in the pixmap property (e.g. the image name) whenever an image is required.</p>
<h5><aname="4-3-3"></a>Layouts</h5>
<p>Click the 'Default Margin' spinbox or the 'Default Spacing' spinbox to change the default layout settings of the current form.</p>
<p>To use the functions in the generated code to dynamically retrieve values for the layout's default margin and spacing, check the Use Functions chechbox. In the Margin and Spacing line edits, specify the function names (no signatures or parantheses) which should be used to retrieve the margin and spacing.</p>
<p>The <em>Edit Custom Widgets</em> dialog is invoked by clicking <b>Tools|Custom|Edit Custom Widgets</b>. Use this dialog to create custom widgets.</p>
<p>Custom widgets are created in code. They may contain a combination of existing widgets but with additional functionality, slots and signals, or they may be written from scratch, or a mixture of both. A custom widget is often a specialization (subclass) of another widget or a combination of widgets working together or a blend of both these approaches. If you simply want a collection of widgets in a particular configuration it is easiest to create them, select them as a group, and copy and paste them as retquired within <em>TQt Designer</em>. Custom widgets are generally created when you need to add new functionality to existing widgets or groups of widgets. To add create a new widget, click the <b>New Widget</b> button. You will find more information about adding new widgets in the 'Definitions Section'. To load a file which contains descriptions of custom widgets, click the <b>Load Descriptions</b> button. Clicking this button invokes the <em>Open Dialog</em>. To save the descriptions of the listed custom widgets, click the <b>Save Descriptions</b> button, which invokes the <em>Save As Dialog</em>. To delete a widget, click the widget in the listbox and then click the <b>Delete Widget</b> button.</p>
<p>Custom widgets are created in code. They may contain a combination of existing widgets but with additional functionality, slots and signals, or they may be written from scratch, or a mixture of both. A custom widget is often a specialization (subclass) of another widget or a combination of widgets working together or a blend of both these approaches. If you simply want a collection of widgets in a particular configuration it is easiest to create them, select them as a group, and copy and paste them as required within <em>TQt Designer</em>. Custom widgets are generally created when you need to add new functionality to existing widgets or groups of widgets. To add create a new widget, click the <b>New Widget</b> button. You will find more information about adding new widgets in the 'Definitions Section'. To load a file which contains descriptions of custom widgets, click the <b>Load Descriptions</b> button. Clicking this button invokes the <em>Open Dialog</em>. To save the descriptions of the listed custom widgets, click the <b>Save Descriptions</b> button, which invokes the <em>Save As Dialog</em>. To delete a widget, click the widget in the listbox and then click the <b>Delete Widget</b> button.</p>
<p>Click <b>Close</b> to leave the Edit Custom Widgets dialog.</p>
<p>The 'Setup Toolbar' wizard page is used to populate a toolbar with actions from each of the default action categories. Click the Category combobox to select which set of actions you wish to work on. The Actions listbox lists the actions available for the current category. The Toolbar listbox lists the toolbar buttons you want to create. Click the blue left and right arrow buttons to move actions into or out of the Toolbar list box. Click the blue up and down arrow buttons to move actions up and down within the Toolbar list box. Note that the '<Separator>' item in the Actions list box may be moved to the Toolbar list box as often as retquired and will cause a separator to appear in the finished toolbar.</p>
<p>The 'Setup Toolbar' wizard page is used to populate a toolbar with actions from each of the default action categories. Click the Category combobox to select which set of actions you wish to work on. The Actions listbox lists the actions available for the current category. The Toolbar listbox lists the toolbar buttons you want to create. Click the blue left and right arrow buttons to move actions into or out of the Toolbar list box. Click the blue up and down arrow buttons to move actions up and down within the Toolbar list box. Note that the '<Separator>' item in the Actions list box may be moved to the Toolbar list box as often as required and will cause a separator to appear in the finished toolbar.</p>
<p>Click <b>Back</b> if you want to return to the 'Choose available menus and toolbars' wizard page. Click <b>Finish</b> to populate the main window and to exit the wizard. Click <b>Cancel</b> on any of the wizard pages to leave the wizard without making any changes.</p>
<h3><aname="3"></a>Data Table Wizard</h3>
<p>The Data Table Wizard is automatically invoked by clicking the datatable widget and placing it on the form. The datatable widget is used to create tabular views of database data.</p>
<p>This tag is only relevant to Windows users.</p>
<p>If you have a class that retquires some Windows-specific export macro, e.g. for classes in a DLL that need to be declared like this: <tt>class win_specific_declaration_goes_here Class</tt>, you can use the <tt><exportmacro></tt> tag. (In standard TQt we use the <tt>Q_EXPORT</tt> macro, e.g. <tt>class Q_EXPORT TQWidget</tt>.) If you use this tag you must also:</p>
<p>If you have a class that requires some Windows-specific export macro, e.g. for classes in a DLL that need to be declared like this: <tt>class win_specific_declaration_goes_here Class</tt>, you can use the <tt><exportmacro></tt> tag. (In standard TQt we use the <tt>Q_EXPORT</tt> macro, e.g. <tt>class Q_EXPORT TQWidget</tt>.) If you use this tag you must also:</p>
<oltype=1><li><p><ahref="designer-manual-16.html#1-11">include</a> the file which contains the macro definition;</p>
<li><p>add the export macro to the form -- this is achieved by entering the macro's name in the 'export macro' sub-property of the form's name property.</p>
</ol><p>Following these steps will ensure that <ahref="uic.html">uic</a> will create the correct <tt>class YOUR_MACRO Form</tt> declarations.</p>
<blockquote><palign="center"><em>Main Window Wizard- Choosing menus and toolbars</em></p></blockquote>
<li><!-- index Creating Toolbars --><!-- index Toolbars, Creating --><!-- index Toolbar Buttons!Adding --><!-- index Adding!Toolbar Buttons --><!-- index Separator!Menu item --><!-- index Separator!Toolbar button --><p>The <em>Setup Toolbar</em> wizard page is used to populate a toolbar with actions from each of the default action categories. The Category combobox is used to select which set of actions you wish to choose from. The Actions list box lists the actions available for the current category. The Toolbar listbox lists the toolbar buttons you want to create. The blue left and right arrow buttons are used to move actions into or out of the Toolbar list box. The blue up and down arrow buttons are used to move actions up and down within the Toolbar list box. Note that the '<Separator>' item in the Actions list box may be moved to the Toolbar list box as often as retquired and will cause a separator to appear in the finished toolbar.</p>
<li><!-- index Creating Toolbars --><!-- index Toolbars, Creating --><!-- index Toolbar Buttons!Adding --><!-- index Adding!Toolbar Buttons --><!-- index Separator!Menu item --><!-- index Separator!Toolbar button --><p>The <em>Setup Toolbar</em> wizard page is used to populate a toolbar with actions from each of the default action categories. The Category combobox is used to select which set of actions you wish to choose from. The Actions list box lists the actions available for the current category. The Toolbar listbox lists the toolbar buttons you want to create. The blue left and right arrow buttons are used to move actions into or out of the Toolbar list box. The blue up and down arrow buttons are used to move actions up and down within the Toolbar list box. Note that the '<Separator>' item in the Actions list box may be moved to the Toolbar list box as often as required and will cause a separator to appear in the finished toolbar.</p>
<p>Copy the New, Open, and Save Actions to the Toolbar list box. Copy a <Separator> to the Toolbar list box. Change the Category to Edit and copy the Cut, Copy, and Find actions to the Toolbar list box. Click <b>Next</b> and then click <b>Finish</b>.</p>
<p>Click <b>File|Save</b> and save the form as <tt>mainform.ui</tt>.</p>
<!-- index Code Editing --><!-- index Subclassing --><!-- index Forward declarations --><!-- index Includes --><!-- index Adding!Code --><!-- index Adding!Forward declarations --><!-- index Adding!Includes --><!-- index Adding!Class variables --><!-- index Class variables --><!-- index Deleting!Forward declarations --><!-- index Deleting!Includes --><!-- index Deleting!Class variables --><!-- index Forms!Forward declarations --><!-- index Forms!Class variables --><!-- index Forms!Code editing --><!-- index Forms!destructor --><!-- index Forms!constructor --><p>In the original version of <em>TQt Designer</em> if you wanted to provide code for a form you had to subclass the form and put your code in the subclass. This version fully supports the subclassing approach, but now provides an alternative: placing your code directly into forms. Writing code in <em>TQt Designer</em> is not quite the same as subclassing, for example you cannot get direct access to the form's constructor or destructor. If you need code to be executed by the constructor create a slot called<!-- index init() --><tt>void init()</tt>; if it exists it will be called from the constructor. Similarly, if you need code to be executed before destruction create a slot called<!-- index destroy() --><tt>void destroy()</tt>. You can also add your own class variables which will be put in the generated constructor's code, and you can add forward declarations and any includes you retquire. To add a variable or declaration, right click the appropriate item, e.g. Class Variables, then click <b>New</b> then enter your text, e.g. <tt>TQString m_filename</tt>. If one or more items exist, right click to pop up a menu that has New, Edit and Delete options. If you want to enter multiple items, e.g. multiple include files or multiple data members, it is easiest to right click in the relevant section, then click <b>Edit</b> to invoke an Edit dialog. To edit code, just click the name of a function to invoke the code editor. Code editing and creating slots are covered later in the chapter.</p>
<!-- index Subclassing --><p>If you subclass the form you create your own<!-- index .cpp --><tt>.cpp</tt> files which can contain your own constructor, destructor, functions, slots, declarations and variables as your retquirements dictate. (See <ahref="designer-manual-6.html#1">Subclassing</a> for more information.)</p>
<!-- index Code Editing --><!-- index Subclassing --><!-- index Forward declarations --><!-- index Includes --><!-- index Adding!Code --><!-- index Adding!Forward declarations --><!-- index Adding!Includes --><!-- index Adding!Class variables --><!-- index Class variables --><!-- index Deleting!Forward declarations --><!-- index Deleting!Includes --><!-- index Deleting!Class variables --><!-- index Forms!Forward declarations --><!-- index Forms!Class variables --><!-- index Forms!Code editing --><!-- index Forms!destructor --><!-- index Forms!constructor --><p>In the original version of <em>TQt Designer</em> if you wanted to provide code for a form you had to subclass the form and put your code in the subclass. This version fully supports the subclassing approach, but now provides an alternative: placing your code directly into forms. Writing code in <em>TQt Designer</em> is not quite the same as subclassing, for example you cannot get direct access to the form's constructor or destructor. If you need code to be executed by the constructor create a slot called<!-- index init() --><tt>void init()</tt>; if it exists it will be called from the constructor. Similarly, if you need code to be executed before destruction create a slot called<!-- index destroy() --><tt>void destroy()</tt>. You can also add your own class variables which will be put in the generated constructor's code, and you can add forward declarations and any includes you require. To add a variable or declaration, right click the appropriate item, e.g. Class Variables, then click <b>New</b> then enter your text, e.g. <tt>TQString m_filename</tt>. If one or more items exist, right click to pop up a menu that has New, Edit and Delete options. If you want to enter multiple items, e.g. multiple include files or multiple data members, it is easiest to right click in the relevant section, then click <b>Edit</b> to invoke an Edit dialog. To edit code, just click the name of a function to invoke the code editor. Code editing and creating slots are covered later in the chapter.</p>
<!-- index Subclassing --><p>If you subclass the form you create your own<!-- index .cpp --><tt>.cpp</tt> files which can contain your own constructor, destructor, functions, slots, declarations and variables as your requirements dictate. (See <ahref="designer-manual-6.html#1">Subclassing</a> for more information.)</p>
</blockquote>
<h4><aname="4-3"></a>Adding Custom Actions</h4>
<p>We want to provide the user with actions that are specific to our application. We want to provide the ability to switch between the two views we will be offering, and allow the user to add colors and set their preferred options. We'll prepare the way by creating a new menu for the view options and by adding a separator to the toolbar.</p>
<h4><aname="6-5"></a>Editing the Code: Setting Up</h4>
<p>There is quite a lot of code to include in the application, but this does not mean that a lot of typing is retquired! All the code is reproduced here so, if you're reading an electronic copy, you can simply cut and paste. If you're reading a print copy, all the code is provided in <tt>/tools/designer/examples/colortool</tt>; simply open the relevant <tt>.ui.h</tt> files and copy and paste from there into your own version of the project.</p>
<p>There is quite a lot of code to include in the application, but this does not mean that a lot of typing is required! All the code is reproduced here so, if you're reading an electronic copy, you can simply cut and paste. If you're reading a print copy, all the code is provided in <tt>/tools/designer/examples/colortool</tt>; simply open the relevant <tt>.ui.h</tt> files and copy and paste from there into your own version of the project.</p>
<blockquote>
<palign="center"><b> Cutting & Pasting Into the Code Editor</b></p>
<p>If you cut and paste code from this manual, because we've indented the code for readability, the code will be over-indented in <em>TQt Designer</em>. This is easily solved. Simply select the function containing the pasted code (either with the mouse, or <b>Shift+Arrow</b>s) and press <b>Tab</b>: this will make <em>TQt Designer</em> fix the indentation. Note that you must select the <em>entire</em> function, including its name and parameters.</p>
<p>This function is at the heart of the application. It visually presents the data to the user. If the table is "dirty" (e.g. if the user has added or deleted colors in the icon view, or has opened a color file) we will populate the table. We start by deleting the contents of every cell. Next we change the number of rows to equal the number of colors in the colors map. For each color we want to display a little square that shows the color, so we create a pixmap of the retquired size.</p>
<p>This function is at the heart of the application. It visually presents the data to the user. If the table is "dirty" (e.g. if the user has added or deleted colors in the icon view, or has opened a color file) we will populate the table. We start by deleting the contents of every cell. Next we change the number of rows to equal the number of colors in the colors map. For each color we want to display a little square that shows the color, so we create a pixmap of the required size.</p>
<p>We now create an iterator for our colors map, and iterate over every color. The colors map has the user's color names as its keys, and <ahref="qcolor.html">TQColor</a> instances as values. We retrieve the color and fill our pixmap with that color. We then set the "Name" column (column <tt>COL_NAME</tt>), to have the color's name (<tt>it.key()</tt>) and the pixmap we've just filled with that color. <ahref="qcolor.html">TQColor</a>'s <tt>name()</tt> function returns a string that is the hex representation of a color, e.g. "#12AB2F"; we retrieve this and set the second ("Hex") column to this value.</p>
<p>If the user wants to see if which colors are web colors we create a <ahref="qchecktableitem.html">TQCheckTableItem</a>, and check it if it is a web color. (We'll cover <tt>isWebColor()</tt> shortly.) We then insert this <ahref="qchecktableitem.html">TQCheckTableItem</a> into the "Web" column.</p>
<p>Having populated the table we call <tt>adjustColumn()</tt> to ensure that each column is just wide enough to show its widest entry, and show or hide the "Web" column depending on the user's preference.</p>
<p>This is the second revision of this function. Now we only exit if the user has had the opportunity to save any unsaved changes. (We'll make a third and final version of this function later, when we deal with saving user settings.)</p>
<p>Try making and running the program. If you have <tt>rgb.txt</tt> on your system try loading it and saving it under a new name for testing purposes. If you don't have this file, save the standard colors and use those. In the next section we'll cover adding and deleting colors so that you can create your own color files. (If it doesn't build see the <ahref="designer-manual-4.html#6">Troubleshooting</a> section.)</p>
<h4><aname="6-28"></a>Editing the Code: The Edit Options</h4>
<p>Adding a new color, finding a color and handling user options all retquire custom dialogs, so we'll defer them until chapter three when we deal with dialogs.</p>
<p>Adding a new color, finding a color and handling user options all require custom dialogs, so we'll defer them until chapter three when we deal with dialogs.</p>
<p>We create a new options form, passing it TRUE to make it modal. We set the radio buttons depending on the current setting of the <tt>m_clip_as</tt> variable. We set the check box to correspond with the <tt>m_show_web</tt> variable. We execute the form, and if the user clicks <b>OK</b>, we reflect their choices back into the relevant main form variables. If the user changed the <tt>m_show_web</tt> variable (by clicking the webCheckBox), we mark the table as "dirty" since it will need updating. We then call <tt>populate()</tt> which will update the table view if retquired.</p>
<p>We create a new options form, passing it TRUE to make it modal. We set the radio buttons depending on the current setting of the <tt>m_clip_as</tt> variable. We set the check box to correspond with the <tt>m_show_web</tt> variable. We execute the form, and if the user clicks <b>OK</b>, we reflect their choices back into the relevant main form variables. If the user changed the <tt>m_show_web</tt> variable (by clicking the webCheckBox), we mark the table as "dirty" since it will need updating. We then call <tt>populate()</tt> which will update the table view if required.</p>
<p>Because we use our OptionsForm and access its radio buttons and checkbox we must add "optionsform.h", "qradiobutton.h" and "qcheckbox.h" to our includes in implementation. (Click Object Explorer's Members tab, right click "Includes (in Implementation)", then click <b>Edit</b>. Click <b>Add</b> and enter "optionsform.h"; click <b>Add</b> again and enter "qradiobutton.h"; click <b>Add</b> again and enter "qcheckbox.h". Press <b>Enter</b>, then click <b>Close</b>.)</p>
<p>You should now have added the following declarations to your includes (in implementation):</p>
<ul><li><p>Grouping forms that belong together.</p>
<li><p>Sharing images between different forms.</p>
<li><p>Sharing database information between different forms.</p>
</ul><p>The following sections explain these benefits in more detail, and why project management is retquired to achieve them.</p>
</ul><p>The following sections explain these benefits in more detail, and why project management is required to achieve them.</p>
<h4><aname="2-1"></a>Grouping forms</h4>
<p>Grouping forms means that <em>TQt Designer</em> maintains a list of the <tt>.ui</tt> files that belong to the same project. This makes it easy to switch between forms with a single mouse click.</p>
<h4><aname="2-2"></a>Sharing images in a image collection</h4>
<p>In TQt 2.x's <em>TQt Designer</em> each form included the images it retquired and no images were shared. This led to duplication when several forms needed to use the same images. Furthermore the images were stored in the XML <tt>.ui</tt> files which made them large.</p>
<p>In TQt 2.x's <em>TQt Designer</em> each form included the images it required and no images were shared. This led to duplication when several forms needed to use the same images. Furthermore the images were stored in the XML <tt>.ui</tt> files which made them large.</p>
<p>As a workaround, we introduced a pixmap-loading function that you could define in <em>TQt Designer</em>. It then was your responsibility to provide the implementation of this function in your application code. The big disadvantage of this approach was that you couldn't see the images during the design process in <em>TQt Designer</em>. This not only makes designing a form less visually interesting, but also has a noticeable impact on geometry management.</p>
<p>In the TQt 3.0 version of <em>TQt Designer</em> we've introduced the concept of a project image collection. If you use a project you can add images to the project's image collection, and these images can be shared and used by any of the forms you include in the project. The images are stored as PNGs (portable network graphics) in a subdirectory, <tt>images/</tt>, inside the project's directory. Whenever you modify the image collection, <em>TQt Designer</em> creates a source file which contains both the image data in binary format and a function to instantiate the images. The images are accessible by all forms in the project and the data is shared.</p>
<p>A further benefit of using an image collection is that the images are added to the default TQMimeSourceFactory. This way they are accessible from rich-text labels, What's This? context help and even tooltips through standard HTML image tags. The <em>source</em> argument of the image tag is simply the image's name in the image collection. This also works during the design process in <em>TQt Designer</em>.</p>
<p>In most non-trivial database applications you will want to access the database from more than one form. This is why the <tt>.db</tt> file is part of a project, not just part of a single form.</p>
<h4><aname="2-4"></a>.pro files</h4>
<p><em>TQt Designer</em> needs to store information on projects, for example, the list of forms, the image collection and information about available databases and how to access them. The majority of TQt users already use a project file format to create multiplatform makefiles: <tt>tmake</tt> (and with TQt 3.0 <tt>qmake</tt>) project <tt>.pro</tt> files. These files already contain the list of forms, <tt>.ui</tt> files, used in the project for <tt>uic</tt>.</p>
<p>We've extended the sections in the <tt>.pro</tt> file to include the extra information that <em>TQt Designer</em> needs to manage projects. For example, when you add a form to your project in <em>TQt Designer</em>, it is automatically added to the FORMS section of the project file, and thus <tt>qmake</tt> will generate the retquired build rules without any further work. Similarly, the images are added to the IMAGES section and thus gets automatically compiled into your executable.</p>
<p>We've extended the sections in the <tt>.pro</tt> file to include the extra information that <em>TQt Designer</em> needs to manage projects. For example, when you add a form to your project in <em>TQt Designer</em>, it is automatically added to the FORMS section of the project file, and thus <tt>qmake</tt> will generate the required build rules without any further work. Similarly, the images are added to the IMAGES section and thus gets automatically compiled into your executable.</p>
<p>We don't force you to use <tt>qmake</tt>; if you prefer another build system, for example automake/autoconf or jam, you can still continue to use it. Look upon the <tt>.pro</tt> file as a file that describes the GUI part of your application. All you need to do -- as previously -- is add the <tt>.ui</tt> files and the images collection to your own Makefiles.</p>
<h3><aname="3"></a>Extending the functionality of a form</h3>
<p>First let us look at a small figure that shows the relationship between <tt>.ui</tt> files, generated code and application code:</p>
@ -95,7 +95,7 @@ int main( int argc, char *argv[] )
}
</pre>
<p>Note that we're including <tt>creditformbase.h</tt> and instantiating a CreditFormBase object; once we've written our subclass we'll replace the header with our subclass, <tt>creditform.h</tt>, and instantiate a CreditForm.</p>
<p>We can now generate the application with <tt>qmake</tt>, e.g. <tt>qmake -o Makefile credit.pro</tt>, make it and run it. The form should run fine, but doesn't yet have the behaviour we retquire.</p>
<p>We can now generate the application with <tt>qmake</tt>, e.g. <tt>qmake -o Makefile credit.pro</tt>, make it and run it. The form should run fine, but doesn't yet have the behaviour we require.</p>
<h5><aname="1-3-3"></a>Creating the Subclass</h5>
<p>We need to create a header and an implementation file for our subclass. The code for our subclass is minimal. The header file is <tt>qt/tools/designer/examples/credit/creditform.h</tt>:</p>
<pre> #include "creditformbase.h"
@ -174,7 +174,7 @@ FORMS = mainform.ui
LANGUAGE = C++
INCLUDEPATH += $(QTDIR)/tools/designer/uilib
</pre>
<p>We do <em>not</em> include the <tt>creditformbase.ui</tt> file since this file will be read at runtime, as we'll see shortly. We must include the <tt>tqui</tt> library since the functionality we retquire is not part of the standard TQt library.</p>
<p>We do <em>not</em> include the <tt>creditformbase.ui</tt> file since this file will be read at runtime, as we'll see shortly. We must include the <tt>tqui</tt> library since the functionality we require is not part of the standard TQt library.</p>
<h4><aname="2-2"></a>Creating main.cpp</h4>
<p>The<!-- index main.cpp --><tt>main.cpp</tt> is quite standard. It will invoke the form we're going to create in <em>TQt Designer</em> as its main form. This form will then load and execute the dynamic dialog.</p>
<p>The<!-- index create() --><tt>create()</tt> function is a static <ahref="qwidgetfactory.html">TQWidgetFactory</a> function. It loads the specified<!-- index .ui --><tt>.ui</tt> file and returns a pointer to the toplevel <ahref="qwidget.html">TQWidget</a> created from the<!-- index .ui --><tt>.ui</tt> file. We have cast the pointer to <ahref="qdialog.html">TQDialog</a> since we know that the <tt>creditformbase.ui</tt> file defines a <ahref="qdialog.html">TQDialog</a>. After creating the dialog we<!-- index exec() --><tt>exec()</tt> it. If the user clicked <b>OK</b> the dialog returns Accepted and we enter the body of the <tt>if</tt> statement. We want to know the amount of credit that the user selected. We call the<!-- index child() --><tt>child()</tt> function on the dialog passing it the name of the widget we're interested in. The<!-- index child() --><tt>child()</tt> function returns a pointer to the widget with the name we passed, or returns 0 if no widget of that name was found. In the example we call<!-- index child() --><tt>child()</tt> to get a pointer to the 'amountSpinBox'. If the pointer we get back is not 0 we set the rating text to the amount in the dialog's spin box. At the end we delete the dynamic dialog. Deleting the dialog ensures that we free up its resources as soon as it is no longer retquired.</p>
<p>The<!-- index create() --><tt>create()</tt> function is a static <ahref="qwidgetfactory.html">TQWidgetFactory</a> function. It loads the specified<!-- index .ui --><tt>.ui</tt> file and returns a pointer to the toplevel <ahref="qwidget.html">TQWidget</a> created from the<!-- index .ui --><tt>.ui</tt> file. We have cast the pointer to <ahref="qdialog.html">TQDialog</a> since we know that the <tt>creditformbase.ui</tt> file defines a <ahref="qdialog.html">TQDialog</a>. After creating the dialog we<!-- index exec() --><tt>exec()</tt> it. If the user clicked <b>OK</b> the dialog returns Accepted and we enter the body of the <tt>if</tt> statement. We want to know the amount of credit that the user selected. We call the<!-- index child() --><tt>child()</tt> function on the dialog passing it the name of the widget we're interested in. The<!-- index child() --><tt>child()</tt> function returns a pointer to the widget with the name we passed, or returns 0 if no widget of that name was found. In the example we call<!-- index child() --><tt>child()</tt> to get a pointer to the 'amountSpinBox'. If the pointer we get back is not 0 we set the rating text to the amount in the dialog's spin box. At the end we delete the dynamic dialog. Deleting the dialog ensures that we free up its resources as soon as it is no longer required.</p>
<p>We used the<!-- index child() --><tt>child()</tt> to gain access to a widget within the dynamic dialog, passing it the name of the widget we were interested in. In some situations we might not know what a widget is called. We can access the first widget of a specified class by calling<!-- index child() --><tt>child()</tt> with a null widget name and a classname, e.g. <tt>child(0,"TQPushButton")</tt>. This will return a pointer to the first <ahref="qpushbutton.html">TQPushButton</a> it finds (or 0 if there isn't one). If you want pointers to all the widgets of a given class you can call the<!-- index TQObject::queryList() --><tt>TQObject::queryList()</tt> function, passing it the name of the class. It returns a <ahref="qobjectlist.html">TQObjectList</a> pointer which points to every object in the dialog that is derived from the given class. See the online <ahref="http://doc.trolltech.com/qobject.html">TQObject</a> documentation for further details.</p>
<h5><aname="2-3-3"></a>Implementing Slots for Dynamic Dialogs</h5>
<!-- index Signals and Slots!Dynamic Dialogs --><!-- index Dynamic Dialogs --><p>There is one outstanding issue that we haven't addressed: the dynamic dialog does not have the behaviour of the original credit dialog because we have not implemented the <tt>setAmount()</tt> slot. We can implement slots for dynamic dialogs by creating a <ahref="qobject.html">TQObject</a> subclass. We then create an instance of this subclass and pass a pointer to it to the<!-- index TQWidgetFactory::create() --><tt>TQWidgetFactory::create()</tt> function which will connect the dynamic dialog's signals to the slots implemented in our subclass.</p>
@ -260,7 +260,7 @@ private:
};
</pre>
<!-- index Macros!Q_OBJECT --><!-- index Q_OBJECT!Macros --><p>Our class must be a <ahref="qobject.html">TQObject</a> subclass and because we're using signals and slots it must include the <tt>Q_OBJECT</tt> macro. We declare a function and the <tt>setAmount()</tt> slot that we wish to implement as well as a private <ahref="qdialog.html">TQDialog</a> pointer.</p>
<p>The implementation retquires the header files of the classes it uses:</p>
<p>The implementation requires the header files of the classes it uses:</p>
<p>We create a <ahref="qhboxlayout.html">TQHBoxLayout</a> in which we'll place the buttons. We've only shown the rewind button in the code above since all the others are identical except for the names of the buttons, pixmaps and signals. For each of the buttons we retquire we call the <ahref="qpushbutton.html">TQPushButton</a> constructor passing it the appropriate embedded pixmap. We then add it to the layout. Finally we connect the button's<!-- index clicked() --><tt>clicked()</tt> signal to the appropriate <em>signal</em>. Since the<!-- index clicked() --><tt>clicked()</tt> signals aren't specific to our widget we want to emit signals that reflect the widget's use. The <tt>rewind()</tt>, <tt>play()</tt>, etc. signals are meaningful in the context of our widget so we propagate each button's<!-- index clicked() --><tt>clicked()</tt> signal to the appropriate widget-specific signal.</p>
<!-- index Forms!Creating Test Harnesses --><p>The implementation is complete, but to make sure that our widget compiles and runs we'll create a tiny test harness. The test harness will retquire two files, a<!-- index .pro --><tt>.pro</tt> project file and a<!-- index main.cpp --><tt>main.cpp</tt>. The <tt>qt/tools/designer/examples/vcr/vcr.pro</tt> project file:</p>
<p>We create a <ahref="qhboxlayout.html">TQHBoxLayout</a> in which we'll place the buttons. We've only shown the rewind button in the code above since all the others are identical except for the names of the buttons, pixmaps and signals. For each of the buttons we require we call the <ahref="qpushbutton.html">TQPushButton</a> constructor passing it the appropriate embedded pixmap. We then add it to the layout. Finally we connect the button's<!-- index clicked() --><tt>clicked()</tt> signal to the appropriate <em>signal</em>. Since the<!-- index clicked() --><tt>clicked()</tt> signals aren't specific to our widget we want to emit signals that reflect the widget's use. The <tt>rewind()</tt>, <tt>play()</tt>, etc. signals are meaningful in the context of our widget so we propagate each button's<!-- index clicked() --><tt>clicked()</tt> signal to the appropriate widget-specific signal.</p>
<!-- index Forms!Creating Test Harnesses --><p>The implementation is complete, but to make sure that our widget compiles and runs we'll create a tiny test harness. The test harness will require two files, a<!-- index .pro --><tt>.pro</tt> project file and a<!-- index main.cpp --><tt>main.cpp</tt>. The <tt>qt/tools/designer/examples/vcr/vcr.pro</tt> project file:</p>
<pre>TEMPLATE = app
LANGUAGE = C++
TARGET = vcr
@ -104,12 +104,12 @@ DBFILE = vcr.db
</ol><p>The remaining items to be completed will depend on the characteristics of the widget you've created. If, for example, your widget can be used to contain other widgets you'd check the Container Widget checkbox. In the case of our Vcr example the only items we need to add are its signals.</p>
<p>Click the Signals tab. Click the <b>New Signal</b> button and type in the signal name 'rewind()'. Click <b>New Signal</b> again and this time type in 'play()'. Add the 'next()' and 'stop()' signals in the same way.</p>
<p>Since our example hasn't any slots or properties we've finished and can click <b>Close</b>. A new icon will appear in <em>TQt Designer</em>'s toolbars which represents the new widget. If you create a new form you can add Vcr widgets and connect the Vcr's signals to your slots.</p>
<p>Incorporating custom widgets that have their own slots and properties is achieved in a similar way to adding signals. All the retquired information is in our custom widget's header file.</p>
<p>Incorporating custom widgets that have their own slots and properties is achieved in a similar way to adding signals. All the required information is in our custom widget's header file.</p>
<aname="creatingplugins"></a><h3><aname="2"></a>Creating Custom Widgets with Plugins</h3>
<!-- index Custom Widgets!Plugins --><!-- index Plugins!Implementing Custom Widgets --><p>This section will show you how to write a custom widget and how to embed the custom widget into a plugin. There are no restrictions or special considerations that must be taken into account when creating a widget that is destined to become a plugin. If you are an experienced TQt programmer you can safely skip the section on creating a custom widget and go directly to <ahref="designer-manual-7.html#2-2">Creating a Plugin</a>.</p>
<p>Be aware that if you use the plugin approach to custom widgets, the plugin needs to be available not only to <em>TQt Designer</em> but also to <tt>uic</tt> at compile-time.</p>
<h4><aname="2-1"></a>Creating a Custom Widget</h4>
<!-- index Creating Custom Widgets --><!-- index Widgets!Creating a Custom Widget --><!-- index Subclassing!Widgets --><p>A custom widget is often a specialization (subclass) of another widget or a combination of widgets working together or a blend of both these approaches. If you simply want a collection of widgets in a particular configuration it is easiest to create them, select them as a group, and copy and paste them as retquired within <em>TQt Designer</em>. Custom widgets are generally created when you need to add new functionality to existing widgets or groups of widgets.</p>
<!-- index Creating Custom Widgets --><!-- index Widgets!Creating a Custom Widget --><!-- index Subclassing!Widgets --><p>A custom widget is often a specialization (subclass) of another widget or a combination of widgets working together or a blend of both these approaches. If you simply want a collection of widgets in a particular configuration it is easiest to create them, select them as a group, and copy and paste them as required within <em>TQt Designer</em>. Custom widgets are generally created when you need to add new functionality to existing widgets or groups of widgets.</p>
<!-- index Properties!Creating Custom Properties --><p>We have two recommendations that you should consider when creating a custom widget for a plugin:</p>
<oltype=1><li><p>Using TQt's property system will provide <em>TQt Designer</em> users with a direct means of configuring the widget through the property editor. (See the <ahref="http://doc.trolltech.com/properties.html">TQt Properties</a> documentation.)</p>
<li><p>Consider making your widget's public 'set' functions into public slots so that you can perform signal-slot connections with the widget in <em>TQt Designer</em>.</p>
@ -128,7 +128,7 @@ DBFILE = vcr.db
</pre>
<p>Our widget will be derived from <ahref="qwidget.html">TQWidget</a> so we include the <tt>qwidget.h</tt> header file. We also forward declare the two classes that our widget will be built from.</p>
<pre></pre>
<!-- index Macros!Q_OBJECT --><!-- index Q_OBJECT --><!-- index Macros!Q_ENUMS --><!-- index Q_ENUMS --><p>We include the <tt>Q_OBJECT</tt> macro since this is retquired for classes that declare signals or slots. The <tt>Q_ENUMS</tt> declaration is used to register the Mode enumeration. Our widget has two properties, mode, to store whether the user should select a File or a Directory and fileName which stores the file or directory they chose.</p>
<!-- index Macros!Q_OBJECT --><!-- index Q_OBJECT --><!-- index Macros!Q_ENUMS --><!-- index Q_ENUMS --><p>We include the <tt>Q_OBJECT</tt> macro since this is required for classes that declare signals or slots. The <tt>Q_ENUMS</tt> declaration is used to register the Mode enumeration. Our widget has two properties, mode, to store whether the user should select a File or a Directory and fileName which stores the file or directory they chose.</p>
<pre> class QT_WIDGET_PLUGIN_EXPORT FileChooser : public <ahref="qwidget.html">TQWidget</a>
{
Q_OBJECT
@ -222,7 +222,7 @@ DBFILE = vcr.db
<p>When <tt>chooseFile()</tt> is called it presents the user with a file or directory dialog depending on the mode. If the user chooses a file or directory the <ahref="qlineedit.html">TQLineEdit</a> is updated with the chosen file or directory and the <tt>fileNameChanged()</tt> signal is emitted.</p>
<p>Although these two files complete the implementation of the FileChooser widget it is good practice to write a test harness to check that the widget behaves as expected before attempting to put it into a plugin.</p>
<h5><aname="2-1-3"></a>Testing the Implementation</h5>
<!-- index main.cpp --><!-- index Forms!Creating Test Harnesses --><p>We present a rudimentary test harness which will allow us to run our custom widget. The test harness retquires two files, a <tt>main.cpp</tt> to contain the FileChooser, and a <tt>.pro</tt> file to create the Makefile from. Here is <tt>qt/tools/designer/examples/filechooser/widget/main.cpp</tt>:</p>
<!-- index main.cpp --><!-- index Forms!Creating Test Harnesses --><p>We present a rudimentary test harness which will allow us to run our custom widget. The test harness requires two files, a <tt>main.cpp</tt> to contain the FileChooser, and a <tt>.pro</tt> file to create the Makefile from. Here is <tt>qt/tools/designer/examples/filechooser/widget/main.cpp</tt>:</p>
<p>We can create the makefile using <tt>qmake</tt>: <tt>qmake -o Makefile filechooser.pro</tt>, then we can make and run the harness to test our new widget. Once we're satisfied that the custom widget is robust and has the behaviour we retquire we can embed it into a plugin.</p>
<p>We can create the makefile using <tt>qmake</tt>: <tt>qmake -o Makefile filechooser.pro</tt>, then we can make and run the harness to test our new widget. Once we're satisfied that the custom widget is robust and has the behaviour we require we can embed it into a plugin.</p>
<h4><aname="2-2"></a>Creating a Plugin</h4>
<!-- index Creating Plugins --><!-- index Plugins!Creating a Plugin --><!-- index Component!Plugins --><p>TQt Plugins can be used to provide self-contained software components for TQt applications. TQt currently supports the creation of five kinds of plugins: codecs, image formats, database drivers, styles and custom widgets. In this section we will explain how to convert our filechooser custom widget into a <em>TQt Designer</em> custom widget plugin.</p>
<p>A <em>TQt Designer</em> custom widget plugin is always derived from <ahref="qwidgetplugin.html">TQWidgetPlugin</a>. The amout of code that needs to be written is minimal.</p>
<p>To make your own plugin it is probably easiest to start by copying our example<!-- index plugin.h --><tt>plugin.h</tt> and<!-- index plugin.cpp --><tt>plugin.cpp</tt> files and changing 'CustomWidgetPlugin' to the name you wish to use for your widget plugin implementation class. Below we provide an introduction to the header file although it needs no changes beyond class renaming. The implementation file retquires simple changes, mostly more class renaming; we will review each function in turn and explain what you need to do.</p>
<p>To make your own plugin it is probably easiest to start by copying our example<!-- index plugin.h --><tt>plugin.h</tt> and<!-- index plugin.cpp --><tt>plugin.cpp</tt> files and changing 'CustomWidgetPlugin' to the name you wish to use for your widget plugin implementation class. Below we provide an introduction to the header file although it needs no changes beyond class renaming. The implementation file requires simple changes, mostly more class renaming; we will review each function in turn and explain what you need to do.</p>
<p>We have called our header file<!-- index plugin.h --><tt>plugin.h</tt> and we've called our plugin class <b>CustomWidgetPlugin</b> since we will be using our plugin class to wrap our custom widgets. We present the entire header file to give you an impression of the scope of the implementation retquired. Most of the functions retquire just a few lines of code.</p>
<p>We have called our header file<!-- index plugin.h --><tt>plugin.h</tt> and we've called our plugin class <b>CustomWidgetPlugin</b> since we will be using our plugin class to wrap our custom widgets. We present the entire header file to give you an impression of the scope of the implementation required. Most of the functions require just a few lines of code.</p>
<!-- index TQSqlDatabase::database() --><p>You do not need to keep a reference to database connections. If you use a single database connection, this becomes the default connection and database functions will use this connection automatically. We can always get a pointer to any of our connections by calling <tt>TQSqlDatabase::database()</tt>.</p>
<p>If you create a <tt>main.cpp</tt> file using <em>TQt Designer</em>, this file will <em>not</em> include <tt>createConnections()</tt>. We do not include this function because it needs the username and password for the database connection, and you may prefer to handle these differently from our simple example function. As a result, applications that preview correctly in <em>TQt Designer</em> will not run unless you implement your own database connections function.</p>
<p><ahref="qdatatable.html">TQDataTable</a>s may be placed on any form to provide browsing of database tables and views. <ahref="qdatatable.html">TQDataTable</a>s can also be used to update or delete records in-place, i.e. inside the cells themselves. Inserting records via a <ahref="qdatatable.html">TQDataTable</a> usually retquires connecting to the<!-- index primeInsert() --><tt>primeInsert()</tt> signal, so that we can generate primary keys for example, or provide default values. If we wish to present records using a form view (perhaps combining data from several tables and views) we might use several <ahref="qdatabrowser.html">TQDataBrowser</a>s and <ahref="qdataview.html">TQDataView</a>s.</p>
<p><ahref="qdatatable.html">TQDataTable</a>s may be placed on any form to provide browsing of database tables and views. <ahref="qdatatable.html">TQDataTable</a>s can also be used to update or delete records in-place, i.e. inside the cells themselves. Inserting records via a <ahref="qdatatable.html">TQDataTable</a> usually requires connecting to the<!-- index primeInsert() --><tt>primeInsert()</tt> signal, so that we can generate primary keys for example, or provide default values. If we wish to present records using a form view (perhaps combining data from several tables and views) we might use several <ahref="qdatabrowser.html">TQDataBrowser</a>s and <ahref="qdataview.html">TQDataView</a>s.</p>
<h4><aname="2-1"></a>Quickly Viewing a Database Table</h4>
<p>This example, along with all the other examples in this chapter, has the project name 'book' and uses the database created by the<!-- index book.sql --><tt>book.sql</tt> script. As we work through the chapter we will build the 'book' application step by step. Create or copy the <tt>qt/tools/designer/examples/book/book1/main.cpp</tt> file shown earlier. The project file for this first example is <tt>qt/tools/designer/examples/book/book1/book.pro</tt>. Start a new project by clicking <b>File|New</b>, then click the 'C++ Project' icon to invoke the <em>Project Settings</em> dialog. Click the ellipsis button to invoke the <em>Save As</em> dialog; navigate to the project's directory (creating it if necessary). Make sure you're in the project's directory, then enter a project name of 'book.pro'. Click the <b>Save</b> button to return to the <em>Project Settings</em> dialog, then click <b>OK</b>. Now click <b>Project|Database Connections</b>. Fill in the connection information appropriate to your database then press <b>Connect</b>. The connection name should now appear in the left hand list box. (If this doesn't happen you'll need to contact your database systems administrator for help.) Close the dialog.</p>
<p>We will now create a new form with a <ahref="qdatatable.html">TQDataTable</a> that's connected to one of our database tables.</p>
@ -144,7 +144,7 @@ bool createConnections()
<!-- index Foreign Keys --><!-- index Databases!Foreign Keys --><p>In most relational databases tables contain fields which are foreign keys into other tables. In our 'book' database example the authorid in the book table is a foreign key into the author table. When we present a form to the end user we do not usually want the foreign key itself to be visible but rather the text associated with it. Thus, we would want the author's name to appear rather than the author id when we show book information. In many databases, this can be achieved by using a view. See your database's documentation for details.</p>
</blockquote>
<h4><aname="2-2"></a>Inserting Records in <ahref="qdatatable.html">TQDataTable</a>s</h4>
<!-- index Inserting Records --><!-- index Databases!Inserting Records --><p>Record insertion into a relational database usually retquires the generation of a primary key value which uniquely identifies the record in the table. Also we often want to create default values for some fields to minimize the user's work. We will create a slot to capture the <ahref="qdatatable.html">TQDataTable</a>s<!-- index primeInsert() --><tt>primeInsert()</tt> signal and populate the <ahref="qsqlrecord.html">TQSqlRecord</a> insertion buffer with a unique primary key.</p>
<!-- index Inserting Records --><!-- index Databases!Inserting Records --><p>Record insertion into a relational database usually requires the generation of a primary key value which uniquely identifies the record in the table. Also we often want to create default values for some fields to minimize the user's work. We will create a slot to capture the <ahref="qdatatable.html">TQDataTable</a>s<!-- index primeInsert() --><tt>primeInsert()</tt> signal and populate the <ahref="qsqlrecord.html">TQSqlRecord</a> insertion buffer with a unique primary key.</p>
<oltype=1><li><p>Click <b>Edit|Slots</b> to invoke the <em>Edit Functions</em> dialog. Click <b>New Function</b>, then enter the slot name <tt>primeInsertAuthor(TQSqlRecord*)</tt> into the Function Properties' Function line edit box. Click <b>OK</b>.</p>
<li><p>Click the <b>Connect Signals/Slots</b> toolbar button, then click the AuthorDataTable, drag to the form and release the mouse. The <em>Edit Connections</em> dialog will now appear. Click the<!-- index primeInsert() --><tt>primeInsert()</tt> signal and then the <tt>primeInsertAuthor()</tt> slot to make the connection. Now click <b>OK</b>.</p>
<li><p>Click the Members tab of the Object Explorer window (click <b>Window|Views|Object Explorer</b> to make the window visible if necessary). Click the <tt>primeInsertAuthor()</tt> slot and an editor window will appear.</p>
@ -161,15 +161,15 @@ bool createConnections()
</pre>
<p>A <ahref="qsqlquery.html">TQSqlQuery</a> object is used to increment and retrieve a unique 'sequence' number for the author table. The signal passed us a pointer to the insertion buffer and we then put the value we've retrieved, i.e. the next sequence number, into the buffer's id field. (Again, note that SQL databases often support a native 'sequence' function. The method used here is inappropriate for production systems, and is for example purposes only. See your database's documentation for details on how to generate unique keys in code. In many cases, the database can generate them automatically, or the database may provide a special syntax for dealing with sequences.)</p>
</ol><!-- index Deleting!Records!Databases --><!-- index Databases!Deleting Records --><!-- index Updating Records --><!-- index Databases!Updating Records --><p>If we rebuild the application it will now support <tt>INSERT</tt> as well as <tt>UPDATE</tt> and <tt>DELETE</tt>. We could easily have added additional code to insert default values, e.g. today's date into a date field, if necessary.</p>
<!-- index Databases!Browsing --><!-- index Databases!Confirmations --><!-- index Browsing Databases --><p>Browsing is supported by clicking records and by using the arrow keys. Once a record is active (highlighted) we can edit the it. Press the <b>Insert</b> key to <tt>INSERT</tt> a new record; press <b>F2</b> to <tt>UPDATE</tt> the current record; press the <b>Del</b> key to <tt>DELETE</tt> the current record. All these operations take place immediately. Users can be given the opportunity to confirm their edits by setting the <ahref="qdatatable.html">TQDataTable</a>'s confirmEdits property to True. If the confirmEdits property is True then user confirmation will be retquired for all insertions, updates and deletes. For finer control you can set the confirmInsert, confirmUpdate and confirmDelete properties individually.</p>
<!-- index Databases!Browsing --><!-- index Databases!Confirmations --><!-- index Browsing Databases --><p>Browsing is supported by clicking records and by using the arrow keys. Once a record is active (highlighted) we can edit the it. Press the <b>Insert</b> key to <tt>INSERT</tt> a new record; press <b>F2</b> to <tt>UPDATE</tt> the current record; press the <b>Del</b> key to <tt>DELETE</tt> the current record. All these operations take place immediately. Users can be given the opportunity to confirm their edits by setting the <ahref="qdatatable.html">TQDataTable</a>'s confirmEdits property to True. If the confirmEdits property is True then user confirmation will be required for all insertions, updates and deletes. For finer control you can set the confirmInsert, confirmUpdate and confirmDelete properties individually.</p>
<blockquote>
<palign="center"><b><ahref="qdatatable.html">TQDataTable</a> User Interface Interaction</b></p>
<!-- index Databases!User Interface Interaction --><!-- index User Interface Interaction, Databases --><p>The default user-interface behavior for <ahref="qdatatable.html">TQDataTable</a>s is as follows:</p>
<ul><li><p>Users can move to records by clicking the scrollbar and clicking records with the mouse. They can also use the keyboard's navigation keys, e.g. <b>Left Arrow</b>, <b>Right Arrow</b>, <b>Up Arrow</b>, <b>Down Arrow</b>, <b>Page Up</b>, <b>Page Down</b>, <b>Home</b> and <b>End</b>.</p>
<li><p><tt>INSERT</tt> is initiated by right-clicking the record and clicking Insert or by pressing the <b>Ins</b> (Insert) key. The user moves between fields using <b>Tab</b> and <b>Shift+Tab</b>. The <tt>INSERT</tt> will take place if the user presses <b>Enter</b> or <b>Tab</b>s off the last field. If autoEdit is TRUE the insert will take place if the user navigates to another record. <tt>INSERT</tt> is cancelled by pressing <b>Esc</b> (Escape). If autoEdit is FALSE navigating to another record also cancels the <tt>INSERT</tt>. Setting confirmInsert to TRUE will retquire the user to confirm each <tt>INSERT</tt>.</p>
<li><p><tt>UPDATE</tt> is initiated by right-clicking the record and clicking Update or by pressing <b>F2</b>. The update will take place if the user presses Enter or Tabs off the last field. If autoEdit is TRUE the update will take place if the user navigates to another record. <tt>UPDATE</tt> is cancelled by pressing <b>Esc</b>. If autoEdit is FALSE navigating to another record also cancels the <tt>UPDATE</tt>. Setting confirmUpdate to TRUE will retquire the user to confirm each <tt>UPDATE</tt>.</p>
<li><p><tt>DELETE</tt> is achieved by right-clicking the record and clicking Delete or by pressing the <b>Del</b> (Delete) key. Setting confirmDelete to TRUE will retquire the user to confirm each <tt>DELETE</tt>.</p>
</ul><p>You can change this default behavior programmatically if retquired.</p>
<li><p><tt>INSERT</tt> is initiated by right-clicking the record and clicking Insert or by pressing the <b>Ins</b> (Insert) key. The user moves between fields using <b>Tab</b> and <b>Shift+Tab</b>. The <tt>INSERT</tt> will take place if the user presses <b>Enter</b> or <b>Tab</b>s off the last field. If autoEdit is TRUE the insert will take place if the user navigates to another record. <tt>INSERT</tt> is cancelled by pressing <b>Esc</b> (Escape). If autoEdit is FALSE navigating to another record also cancels the <tt>INSERT</tt>. Setting confirmInsert to TRUE will require the user to confirm each <tt>INSERT</tt>.</p>
<li><p><tt>UPDATE</tt> is initiated by right-clicking the record and clicking Update or by pressing <b>F2</b>. The update will take place if the user presses Enter or Tabs off the last field. If autoEdit is TRUE the update will take place if the user navigates to another record. <tt>UPDATE</tt> is cancelled by pressing <b>Esc</b>. If autoEdit is FALSE navigating to another record also cancels the <tt>UPDATE</tt>. Setting confirmUpdate to TRUE will require the user to confirm each <tt>UPDATE</tt>.</p>
<li><p><tt>DELETE</tt> is achieved by right-clicking the record and clicking Delete or by pressing the <b>Del</b> (Delete) key. Setting confirmDelete to TRUE will require the user to confirm each <tt>DELETE</tt>.</p>
</ul><p>You can change this default behavior programmatically if required.</p>
</blockquote>
<h4><aname="2-3"></a>Relating Two Tables Together (Master-Detail)</h4>
<!-- index Databases!Master-Detail Relationships --><!-- index Master-Detail Relationships --><p>Databases often have pairs of tables that are related. For example, an invoice table might list the numbers, dates and customers for invoices, but not the actual invoice items, which an invoice item table might store. In the 'book' application we wish to have a <ahref="qdatatable.html">TQDataTable</a> that we can use to browse through the authors table and a second <ahref="qdatatable.html">TQDataTable</a> to show the books they've written.</p>
@ -210,7 +210,7 @@ bool createConnections()
BookDataTable->refresh();
}
</pre>
<p>All that's retquired now is to change the BookDataTable's filter and refresh the <ahref="qdatatable.html">TQDataTable</a> to show the results of the filter.</p>
<p>All that's required now is to change the BookDataTable's filter and refresh the <ahref="qdatatable.html">TQDataTable</a> to show the results of the filter.</p>
</ol><h5><aname="2-3-2"></a>Preparing the Interface for Drilldown</h5>
<!-- index Databases!Drilldown --><!-- index Drilldown --><p>We can now browse and edit authors and see their books in the BookDataTable. In the next section we explore <ahref="qdatabrowser.html">TQDataBrowser</a>, which will allow us to drill down to a dialog through which we can edit books. For now we will add some buttons to the main BookForm which we will use to invoke the book editing dialog.</p>
<oltype=1><li><p>Click the form, then click the <b>Break Layout</b> toolbar button. Resize the form to make room for some buttons at the bottom.</p>
@ -250,9 +250,9 @@ bool createConnections()
<li><!-- index readFields() --><p><tt>readFields()</tt> to read data from the cursor's edit buffer and<!-- index writeFields() --><tt>writeFields()</tt> to write the form's data to the cursor's edit buffer;</p>
<li><!-- index clearValues() --><p><tt>clearValues()</tt> to clear the form's values.</p>
</ul><p>If you use <em>TQt Designer</em>'s <ahref="qdatabrowser.html">TQDataBrowser</a> wizard you will be given the option of creating a default set of buttons for navigation and editing. The behavior of these buttons is set up using the slots described above to provide the following functionality:</p>
<ul><li><p><tt>INSERT</tt> is initiated by pressing the <b>Ins</b> (Insert) key. The user moves between fields using <b>Tab</b> and <b>Shift+Tab</b>. If the user presses the Update button the <tt>INSERT</tt> will take place and the user will be taken to the record they have just inserted. If the user presses the Insert button (i.e. a second time) the <tt>INSERT</tt> will take place and a new insertion will be initiated. If autoEdit is TRUE the <tt>INSERT</tt> will take place if the user navigates to another record. <tt>INSERT</tt> is cancelled by pressing the <b>Esc</b> key or by pressing the <b>Del</b> (Delete) key. If autoEdit is FALSE then navigating to another record also cancels the <tt>INSERT</tt>. Setting confirmInsert to TRUE will retquire the user to confirm each <tt>INSERT</tt>.</p>
<li><p><tt>UPDATE</tt> is automatically initiated whenever the user navigates to a record. An update will take place if the user presses the Update button. If autoEdit is TRUE the update will take place if the user navigates to another record. <tt>UPDATE</tt> is cancelled by pressing the <b>Esc</b> key or by pressing the <b>Del</b> button. If autoEdit is FALSE then navigating to another record also cancels the <tt>UPDATE</tt>. Setting confirmUpdate to TRUE will retquire the user to confirm each <tt>UPDATE</tt>.</p>
<li><p><tt>DELETE</tt> is achieved by pressing the <b>Del</b> key. Setting confirmDelete to TRUE will retquire the user to confirm each <tt>DELETE</tt>.</p>
<ul><li><p><tt>INSERT</tt> is initiated by pressing the <b>Ins</b> (Insert) key. The user moves between fields using <b>Tab</b> and <b>Shift+Tab</b>. If the user presses the Update button the <tt>INSERT</tt> will take place and the user will be taken to the record they have just inserted. If the user presses the Insert button (i.e. a second time) the <tt>INSERT</tt> will take place and a new insertion will be initiated. If autoEdit is TRUE the <tt>INSERT</tt> will take place if the user navigates to another record. <tt>INSERT</tt> is cancelled by pressing the <b>Esc</b> key or by pressing the <b>Del</b> (Delete) key. If autoEdit is FALSE then navigating to another record also cancels the <tt>INSERT</tt>. Setting confirmInsert to TRUE will require the user to confirm each <tt>INSERT</tt>.</p>
<li><p><tt>UPDATE</tt> is automatically initiated whenever the user navigates to a record. An update will take place if the user presses the Update button. If autoEdit is TRUE the update will take place if the user navigates to another record. <tt>UPDATE</tt> is cancelled by pressing the <b>Esc</b> key or by pressing the <b>Del</b> button. If autoEdit is FALSE then navigating to another record also cancels the <tt>UPDATE</tt>. Setting confirmUpdate to TRUE will require the user to confirm each <tt>UPDATE</tt>.</p>
<li><p><tt>DELETE</tt> is achieved by pressing the <b>Del</b> key. Setting confirmDelete to TRUE will require the user to confirm each <tt>DELETE</tt>.</p>
</ul></blockquote>
<h5><aname="3-1-2"></a>Performing the Drilldown</h5>
<!-- index Databases!Drilldown --><!-- index Drilldown --><p>We now have a working form for editing book records. We need to start the form when the user clicks our 'Edit Books' button, and to navigate to the record they have selected in the BookDataTable. We also need to provide a means of editing the foreign keys, e.g. authorid.</p>
@ -344,7 +344,7 @@ bool createConnections()
}
</pre>
<p>Firstly we look up the book's author and secondly we iterate through the <em>ComboBox</em>'s items until we find the author and set the <em>ComboBox</em>'s current item to the matching author.</p>
</ul></ol><p>If the author name has changed or been deleted the query will fail and no author id will be inserted into the buffer causing the <tt>INSERT</tt> to fail. An alternative is to record the author id's as we populate the <em>ComboBox</em> and store them in a <ahref="qmap.html">TQMap</a> which we can then look up as retquired. This approach retquires changes to the<!-- index init() --><tt>init()</tt>, <tt>beforeUpdateBook()</tt> and <tt>primeInsertBook()</tt> functions and the addition of a new function, <tt>mapAuthor()</tt>. The relevant code from <tt>qt/tools/designer/examples/book/book8/editbook.ui</tt> is shown below.</p>
</ul></ol><p>If the author name has changed or been deleted the query will fail and no author id will be inserted into the buffer causing the <tt>INSERT</tt> to fail. An alternative is to record the author id's as we populate the <em>ComboBox</em> and store them in a <ahref="qmap.html">TQMap</a> which we can then look up as required. This approach requires changes to the<!-- index init() --><tt>init()</tt>, <tt>beforeUpdateBook()</tt> and <tt>primeInsertBook()</tt> functions and the addition of a new function, <tt>mapAuthor()</tt>. The relevant code from <tt>qt/tools/designer/examples/book/book8/editbook.ui</tt> is shown below.</p>
<oltype=1><li><p>First we need to create a class variable to map author names to author id's. Click in the Members tab of the Object Explorer, then right click the Class Variables item and click <b>New</b>. Type in 'TQMap<TQString,int> authorMap;'.</p>
<li><p>We now record the author id's in the<!-- index init() --><tt>init()</tt> function.</p>
<pre> void EditBookForm::init()
@ -389,7 +389,7 @@ bool createConnections()
}
}
</pre>
</ol><!-- index Databases!Foreign Keys --><!-- index Foreign Keys --><p>Another approach which is especially useful if the same foreign key lookups are retquired in different parts of the application is to subclass a cursor and use this for our lookups. This is described in the <ahref="http://doc.trolltech.com/sql.html">TQt SQL Module documentation</a>, particulary the section on subclassing <ahref="qsqlcursor.html">TQSqlCursor</a>.</p>
</ol><!-- index Databases!Foreign Keys --><!-- index Foreign Keys --><p>Another approach which is especially useful if the same foreign key lookups are required in different parts of the application is to subclass a cursor and use this for our lookups. This is described in the <ahref="http://doc.trolltech.com/sql.html">TQt SQL Module documentation</a>, particulary the section on subclassing <ahref="qsqlcursor.html">TQSqlCursor</a>.</p>
<p>The 'book' example demonstrates the basic techniques needed for SQL programming with TQt. Additional information on the TQt SQL classes, especially the <ahref="qsqlquery.html">TQSqlQuery</a> and <ahref="qsqlcursor.html">TQSqlCursor</a> classes is provided in the <ahref="http://doc.trolltech.com/sql.html">TQt SQL Module documentation</a>.</p>
<h3><aname="2"></a>Creating and Using Templates</h3>
<!-- index Creating Templates --><!-- index Templates!Creating and Using --><p><em>TQt Designer</em> supports two approaches to creating template forms. The simplest approach involves little more than saving a<!-- index .ui --><tt>.ui</tt> file into the templates directory. The second approach involves creating a container widget class to be used as a base class for forms that use the template. We will explain both techniques.</p>
<h4><aname="2-1"></a>Simple Templates</h4>
<p>These templates are most useful when you want to create a whole set of forms which all have some common widgets. For example, you might have a project that will retquire many forms, all of which need to be branded with a company name and logo.</p>
<p>These templates are most useful when you want to create a whole set of forms which all have some common widgets. For example, you might have a project that will require many forms, all of which need to be branded with a company name and logo.</p>
<p>First we'll create the simple template.</p>
<oltype=1><li><p>Click <b>File|New</b> to invoke the <em>New File</em> dialog. Click the Dialog template then click <b>OK</b>.</p>
<li><p>Click the <b>Text Label</b> toolbar button, then click near the top left of the form. Change the font Point Size property to 16 and change the <em>text</em> property to your or your company's name. Click the <b>Line</b> toolbar button, then click the form below the label; click Horizontal on the pop-up menu.</p>
<p>If you wish to delete the add-in remove it from the toolbar then delete the<!-- index qmsdev.dll --><tt>qmsdev.dll</tt> file from the add-ins directory.</p>
<h4><aname="3-1"></a>Creating Makefiles without qmake</h4>
<!-- index Makefiles --><p>The <tt>qmake</tt> tool provided with TQt can create Makefiles appropriate to your platform based on<!-- index .pro --><tt>.pro</tt> project files. This section describes the dependencies involved in building a TQt application and gives a couple of simple example Makefiles. This section assumes that you have a good understanding of Makefiles.</p>
<!-- index Macros!Q_OBJECT --><!-- index Q_OBJECT --><p><em>TQt Designer</em> produces<!-- index .ui --><tt>.ui</tt> files which are used to generate<!-- index .h --><tt>.h</tt> and<!-- index .cpp --><tt>.cpp</tt> files for the compiler to compile. The<!-- index .ui --><tt>.ui</tt> files are processed by <tt>uic</tt>. Classes which inherit from <ahref="qobject.html">TQObject</a>, e.g. those which use slots and signals, retquire an additional<!-- index .cpp --><tt>.cpp</tt> file to be generated. These files are generated by the <tt>moc</tt> and are named '<em>moc_</em>file.cpp' where the original<!-- index .cpp --><tt>.cpp</tt> file is called 'file.cpp'. If your<!-- index .cpp --><tt>.cpp</tt> file contains the <tt>Q_OBJECT</tt> macro an additional file 'file.moc' should be generated which must be <tt>#include</tt>d in the<!-- index .cpp --><tt>.cpp</tt>, normally at the end. This retquires an extra dependency being created.</p>
<!-- index Macros!Q_OBJECT --><!-- index Q_OBJECT --><p><em>TQt Designer</em> produces<!-- index .ui --><tt>.ui</tt> files which are used to generate<!-- index .h --><tt>.h</tt> and<!-- index .cpp --><tt>.cpp</tt> files for the compiler to compile. The<!-- index .ui --><tt>.ui</tt> files are processed by <tt>uic</tt>. Classes which inherit from <ahref="qobject.html">TQObject</a>, e.g. those which use slots and signals, require an additional<!-- index .cpp --><tt>.cpp</tt> file to be generated. These files are generated by the <tt>moc</tt> and are named '<em>moc_</em>file.cpp' where the original<!-- index .cpp --><tt>.cpp</tt> file is called 'file.cpp'. If your<!-- index .cpp --><tt>.cpp</tt> file contains the <tt>Q_OBJECT</tt> macro an additional file 'file.moc' should be generated which must be <tt>#include</tt>d in the<!-- index .cpp --><tt>.cpp</tt>, normally at the end. This requires an extra dependency being created.</p>
<p>Processing<!-- index .ui --><tt>.ui</tt> files with <tt>uic</tt> is done <em>twice</em>:</p>
<pre>
uic myform.ui -o myform.h
@ -172,7 +172,7 @@ myform.h: myform.ui
</pre>
<p>To see more sophisticated Makefiles simply generate them using <tt>qmake</tt> on any of your TQt projects or any of the examples supplied with TQt.</p>
<!-- index Foreign File Formats --><p>To import a file in a supported foreign file format click <b>File|Open</b>, then click the File Type combobox to choose the file type you wish to load. Click the retquired file and <em>TQt Designer</em> will convert and load the file.</p>
<!-- index Foreign File Formats --><p>To import a file in a supported foreign file format click <b>File|Open</b>, then click the File Type combobox to choose the file type you wish to load. Click the required file and <em>TQt Designer</em> will convert and load the file.</p>
<p>The filters that <em>TQt Designer</em> uses to read foreign file formats are 'works in progress'. You may have different filters available in your version of <em>TQt Designer</em> than those described here. The easiest way to see which filters are available is to invoke the file open dialog; all your filters are listed in the File Type combobox.</p>
<!-- index Foreign File Formats!TQt Architect --><!-- index TQt Architect --><p><ahref="http://qtarch.sourceforge.net/">TQt Architect</a> is a free GUI builder for TQt written by Jeff Harris and Klaus Ebner. The<!-- index .dlg --><tt>.dlg</tt> extension is associated with TQt Architect dialog files.</p>
<tdalign="right"valign="center"><imgsrc="logo32.png"align="right"width="64"height="32"border="0"></td></tr></table><h1align=center>Porting your applications to TQt/Embedded</h1>
<p> Existing TQt applications should retquire no porting provided there is no
<p> Existing TQt applications should require no porting provided there is no
platform dependent code. Platform dependent code includes system calls,
calls to the underlying window system (Windows or X11), and TQt platform
specific methods such as <ahref="qapplication.html#x11EventFilter">TQApplication::x11EventFilter</a>().
@ -45,7 +45,7 @@ using <tt>#ifdef</tt> directives:
@ -73,10 +73,10 @@ the application usable by people in countries other than one's own.
<!-- endtoc -->
<p> In some cases internationalization is simple, for example, making a US
application accessible to Australian or British users may retquire
application accessible to Australian or British users may require
little more than a few spelling corrections. But to make a US
application usable by Japanese users, or a Korean application usable
by German users, will retquire that the software operate not only in
by German users, will require that the software operate not only in
different languages, but use different input techniques, character
encodings and presentation conventions.
<p> TQt tries to make internationalization as painless as possible for
@ -94,7 +94,7 @@ time.
<li> Greek
<li> Hebrew
<li> Thai and Lao
<li> All scripts in Unicode 3.2 that do not retquire special processing
<li> All scripts in Unicode 3.2 that do not require special processing
</ul>
<p> On Windows NT/2000/XP and Unix/X11 with Xft (client side font support)
the following languages are also supported:
@ -149,7 +149,7 @@ takes a <a href="qrect.html">TQRect</a> since this will align in accordance with
<p><li> When you write your own text input controls, use <ahref="qfontmetrics.html#charWidth">TQFontMetrics::charWidth</a>() to determine the width of a character in a
string. In some languages (e.g. Arabic or languages from the Indian
subcontinent), the width and shape of a glyph changes depending on the
surrounding characters. Writing input controls usually retquires a
surrounding characters. Writing input controls usually requires a
certain knowledge of the scripts it is going to be used in. Usually
the easiest way is to subclass <ahref="qlineedit.html">TQLineEdit</a> or <ahref="qtextedit.html">TQTextEdit</a>.
<p></ul>
@ -394,7 +394,7 @@ support many input and output encodings for your users' data. When an
application starts, the locale of the machine will determine the 8-bit
encoding used when dealing with 8-bit data: such as for font
selection, text display, 8-bit text I/O and character input.
<p> The application may occasionally retquire encodings other than the
<p> The application may occasionally require encodings other than the
default local 8-bit encoding. For example, an application in a
Cyrillic KOI8-R locale (the de-facto standard locale in Russia) might
need to output Cyrillic in the ISO 8859-5 encoding. Code for this
<p>TQt provides excellent support for translating applications into local languages. This Guide explains how to use TQt's translation tools for each of the roles involved in translating an application. The Guide begins with a brief overview of the issues that must be considered, followed by chapters devoted to each role and the supporting tools provided.</p>
<p><ahref="linguist-manual-2.html">Chapter 2: Release Manager</a> is aimed at the person with overall responsibility for the release of the application. They will typically coordinate the work of the software engineers and the translator. The chapter describes the use of two tools. The <ahref="linguist-manual-2.html#2">lupdate</a> tool is used to synchronize source code and translations. The <ahref="linguist-manual-2.html#3">lrelease</a> tool is used to create runtime translation files for use by the released application.</p>
<p><ahref="linguist-manual-3.html">Chapter 3: Translators</a> is for translators. It describes the use of the <em>TQt Linguist</em> tool. No computer knowledge beyond the ability to start a program and use a text editor or word processor is retquired.</p>
<p><ahref="linguist-manual-3.html">Chapter 3: Translators</a> is for translators. It describes the use of the <em>TQt Linguist</em> tool. No computer knowledge beyond the ability to start a program and use a text editor or word processor is required.</p>
<p><ahref="linguist-manual-4.html">Chapter 4: Programmers</a> is for TQt programmers. It explains how to create TQt applications that are able to use translated text. It also provides guidance on how to help the translator identify the context in which phrases appear. This chapter's three short tutorials cover everything the programmer needs to do.</p>
<h3><aname="1"></a>Overview of the Translation Process</h3>
<p>Most of the text that must be translated in an application program consists of either single words or short phrases. These typically appear as window titles, menu items, pop-up help text (balloon help), and labels to buttons, check boxes and radio buttons.</p>
<p>The phrases are entered into the source code by the programmer in their native language using a simple but special syntax to identify that the phrases retquire translation. The TQt tools provide context information for each of the phrases to help the translator, and the programmer is able to add additional context information to phrases when necessary. The release manager generates a set of translation files that are produced from the source files and passes these to the translator. The translator opens the translation files using <em>TQt Linguist</em>, enters their translations and saves the results back into the translation files, which they pass back to the release manager. The release manager then generates fast compact versions of these translation files ready for use by the application. The tools are designed to be used in repeated cycles as applications change and evolve, preserving existing translations and making it easy to identify which new translations are retquired. <em>TQt Linguist</em> also provides a phrase book facility to help ensure consistent translations across multiple applications and projects.</p>
<p>The phrases are entered into the source code by the programmer in their native language using a simple but special syntax to identify that the phrases require translation. The TQt tools provide context information for each of the phrases to help the translator, and the programmer is able to add additional context information to phrases when necessary. The release manager generates a set of translation files that are produced from the source files and passes these to the translator. The translator opens the translation files using <em>TQt Linguist</em>, enters their translations and saves the results back into the translation files, which they pass back to the release manager. The release manager then generates fast compact versions of these translation files ready for use by the application. The tools are designed to be used in repeated cycles as applications change and evolve, preserving existing translations and making it easy to identify which new translations are required. <em>TQt Linguist</em> also provides a phrase book facility to help ensure consistent translations across multiple applications and projects.</p>
<p>Translators and programmers must address a number of issues because of the subtleties and complexities of human language:</p>
<ul><li><p>A single phrase may need to be translated into several different forms depending on context, e.g. <em>open</em> in English might become <em></em><em>öffnen</em>, "open file", or <em>aufbauen</em>, "open internet connection", in German.</p>
<li><p>Keyboard accelerators may need to be changed but without introducing conflicts, e.g. "&Quit" in English becomes "Avslutt" in Norwegian which doesn't contain a "Q". We cannot use a letter that is already in use -- unless we change several accelerators.</p>
<!-- index lupdate --><p>Usage: <tt>lupdate myproject.pro</tt></p>
<!-- index TQt Designer --><p>This is a simple command line tool. <ahref="linguist-manual-2.html#2">lupdate</a> reads a TQt <tt>.pro</tt> project file, finds the translatable strings in the specified source, header and <em>TQt Designer</em> interface files, and produces or updates the <tt>.ts</tt> translation files listed in the project file. The translation files are given to the translator who uses <em>TQt Linguist</em> to read the files and insert the translations.</p>
<p>Companies that have their own translators in-house may find it useful to run <ahref="linguist-manual-2.html#2">lupdate</a> regularly, perhaps monthly, as the application develops. This will lead to a fairly low volume of translation work spread evenly over the life of the project and will allow the translators to support a number of projects simultaneously.</p>
<p>Companies that hire in translators as retquired may prefer to run <ahref="linguist-manual-2.html#2">lupdate</a> only a few times in the application's life cycle, the first time might be just before the first test phase. This will provide the translator with a substantial single block of work and any bugs that the translator detects may easily be included with those found during the initial test phase. The second and any subsequent <ahref="linguist-manual-2.html#2">lupdate</a> runs would probably take place during the final beta phase.</p>
<!-- index .ts Files --><!-- index Translation Source Files --><!-- index XML --><p>The <tt>.ts</tt> file format is a simple human-readable XML format that can be used with version control systems if retquired.</p>
<p>Companies that hire in translators as required may prefer to run <ahref="linguist-manual-2.html#2">lupdate</a> only a few times in the application's life cycle, the first time might be just before the first test phase. This will provide the translator with a substantial single block of work and any bugs that the translator detects may easily be included with those found during the initial test phase. The second and any subsequent <ahref="linguist-manual-2.html#2">lupdate</a> runs would probably take place during the final beta phase.</p>
<!-- index .ts Files --><!-- index Translation Source Files --><!-- index XML --><p>The <tt>.ts</tt> file format is a simple human-readable XML format that can be used with version control systems if required.</p>
<h3><aname="3"></a>lrelease</h3>
<!-- index lrelease --><p>Usage: <tt>lrelease myproject.pro</tt></p>
<!-- index .qm Files --><!-- index TQt Message Files --><p>This is another simple command line tool. It reads a TQt <tt>.pro</tt> project file and produces the <tt>.qm</tt> files used by the application, one for each <tt>.ts</tt> translation source file listed in the project file. The <tt>.qm</tt> file format is a compact binary format that provides extremely fast lookups for translations.</p>
<p>This tool is run whenever a release of the application is to be made, from initial test version through to final release version. If the <tt>.qm</tt> files are not created, e.g. because an alpha release is retquired before any translation has been undertaken, the application will run perfectly well using the text the programmers placed in the source files. Once the <tt>.qm</tt> files are available the application will detect them and use them automatically.</p>
<p>This tool is run whenever a release of the application is to be made, from initial test version through to final release version. If the <tt>.qm</tt> files are not created, e.g. because an alpha release is required before any translation has been undertaken, the application will run perfectly well using the text the programmers placed in the source files. Once the <tt>.qm</tt> files are available the application will detect them and use them automatically.</p>
<p>Note that <ahref="linguist-manual-2.html#3">lrelease</a> will only incorporate translations that are marked as "done". If a translation is missing, or has failed validation, the original text will be used instead.</p>
<h3><aname="4"></a>Missing Translations</h3>
<p>Both <ahref="linguist-manual-2.html#2">lupdate</a> and <ahref="linguist-manual-2.html#3">lrelease</a> may be used with <tt>.ts</tt> translation source files which are incomplete. Missing translations will be replaced with the native language phrases at runtime.</p>
<!-- index Linguist --><!-- index TQt Linguist --><!-- index Contexts!for Translation --><p><em>TQt Linguist</em> is a tool for adding translations to TQt applications. It introduces the concept of a translation "context" which means a group of phrases that appear together on the screen e.g. in the same menu or dialog.</p>
<p>To start, run <em>TQt Linguist</em>, either from the taskbar menu, or by double clicking the desktop icon, or type <tt>linguist</tt> (followed by <b>Enter</b>) at the command line. Once <em>TQt Linguist</em> has started choose <b>File|Open</b> from the menu bar and select a <tt>.ts</tt> translation source file to work on.</p>
<p><em>TQt Linguist</em>'s main window is divided into four main areas. The left hand side contains the Context list, the top right is the Source text area, the middle right is the translation area and the bottom right is the phrases and guesses area. We'll describe them in detail later.</p>
<p>Click on one of the contexts in the context list (left hand side) and then click on one of the phrases that appears in the Source text area (top right). The phrase will be copied into the translation area (middle right). Click under the word 'Translation' and type in the translation. Click <b>Ctrl+Enter</b> (Done & Next) to confirm that you have completed the translation and to move on to the next phrase that retquires translation.</p>
<p>Click on one of the contexts in the context list (left hand side) and then click on one of the phrases that appears in the Source text area (top right). The phrase will be copied into the translation area (middle right). Click under the word 'Translation' and type in the translation. Click <b>Ctrl+Enter</b> (Done & Next) to confirm that you have completed the translation and to move on to the next phrase that requires translation.</p>
<p>The cycle of entering a translation then pressing <b>Ctrl+Enter</b> can be repeated until all the translations are done or until you finish the session. Linguist will attempt to fill the "phrases and guesses" area with possible translations from any open phrase books and any previous translations. Each has a keyboard shortcut, e.g. <b>Ctrl+1</b>, <b>Ctrl+2</b>, etc., which you can use to copy the guess into the Translation area. (Mouse users can double click a phrase or guess to move it into the Translation area.) At the end of the session choose <b>File|Save</b> from the menu bar and then <b>File|Exit</b> to quit.</p>
<h3><aname="2"></a>TQt Linguist's Main Window</h3>
<p>To add a new phrase click the <b>New Phrase</b> button (or press Alt+N) and type in a new source phrase. Press Tab and type in the translation. Optionally press Tab and enter a definition -- this is useful to distinguish different translations of the same source phrase. This process may be repeated as often as necessary.</p>
<p>You can delete a phrase by selecting it in the phrases list and clicking Remove Phrase.</p>
<p>Click the <em>Save</em> button (press Alt+S) and then click the <em>Close</em> button (press Esc) once you've finished adding (and removing) phrases.</p>
<p>When a phrase or set of phrases appears in the phrase book double clicking the retquired target phrase will copy it to the translation pane at the text cursor position. If you want to <em>replace</em> the text in the translation pane with the target phrase, click the translation pane, choose <b>Edit|Select All</b> (press <b>Alt+A</b>) and then double click the target phrase.</p>
<p>When a phrase or set of phrases appears in the phrase book double clicking the required target phrase will copy it to the translation pane at the text cursor position. If you want to <em>replace</em> the text in the translation pane with the target phrase, click the translation pane, choose <b>Edit|Select All</b> (press <b>Alt+A</b>) and then double click the target phrase.</p>
<h3><aname="5"></a>Validation</h3>
<!-- index Validation of Translations --><!-- index Accelerators!Validation --><!-- index Punctuation!Validation --><!-- index Phrases!Validation --><p><em>TQt Linguist</em> provides three kinds of validation on translated phrases.</p>
<oltype=1><li><p><em>Accelerator validation</em> detects translated phrases that do not have an ampersand when the source phrase does and vice versa.</p>
<p>Support for multiple languages is extremely simple in TQt applications, and adds little overhead to the programmer's workload.</p>
<p>TQt minimizes the performance cost of using translations by translating the phrases for each window as they are created. In most applications the main window is created just once. Dialogs are often created once and then shown and hidden as retquired. Once the initial translation has taken place there is no further runtime overhead for the translated windows. Only those windows that are created, destroyed and subsequently created will have a translation performance cost.</p>
<p>Creating applications that can switch language at runtime is possible with TQt, but retquires a certain amount of programmer intervention and will of course incur some runtime performance cost.</p>
<p>TQt minimizes the performance cost of using translations by translating the phrases for each window as they are created. In most applications the main window is created just once. Dialogs are often created once and then shown and hidden as required. Once the initial translation has taken place there is no further runtime overhead for the translated windows. Only those windows that are created, destroyed and subsequently created will have a translation performance cost.</p>
<p>Creating applications that can switch language at runtime is possible with TQt, but requires a certain amount of programmer intervention and will of course incur some runtime performance cost.</p>
<h3><aname="1"></a>Making the Application Translation Aware</h3>
<p>Programmers should make their application look for and load the appropriate translation file and mark user-visible text and Ctrl keyboard accelerators as targets for translation.</p>
<p>Each piece of text that retquires translating retquires context to help the translator identify where in the program the text occurs. In the case of multiple identical texts that retquire different translations, the translator also retquires some information to disambiguate the source texts. Marking text for translation will automatically cause the class name to be used as basic context information. In some cases the programmer may be retquired to add additional information to help the translator.</p>
<p>Each piece of text that requires translating requires context to help the translator identify where in the program the text occurs. In the case of multiple identical texts that require different translations, the translator also requires some information to disambiguate the source texts. Marking text for translation will automatically cause the class name to be used as basic context information. In some cases the programmer may be required to add additional information to help the translator.</p>
<!-- index .ts Files --><!-- index Translation Source Files --><p>Translation files consist of all the user-visible text and Ctrl key accelerators in an application and translations of that text. Translation files are created as follows:</p>
<!-- index lupdate --><!-- index lrelease --><oltype=1><li><p>Run <ahref="linguist-manual-2.html#2">lupdate</a> initially to generate the first set of <tt>.ts</tt> translation source files with all the user-visible text but no translations.</p>
@ -447,7 +447,7 @@ TRANSLATIONS = tt3_pt.ts
but = new <ahref="qradiobutton.html">TQRadioButton</a>( <ahref="qobject.html#tr">tr</a>("Disabled"), colors );
<p>Notice the two occurrences of <tt>tr("Enabled")</tt> and of <tt>tr("Disabled")</tt> in PrintPanel. Since both "Enabled"s and "Disabled"s appear in the same context <em>TQt Linguist</em> will only display one occurrence of each and will use the same translations for the duplicates that it doesn't display. Whilst this is a useful timesaver, in some languages, such as Portuguese, the second occurrence retquires a separate translation. We will see how <em>TQt Linguist</em> can be made to display all the occurrences for separate translation shortly.</p>
<p>Notice the two occurrences of <tt>tr("Enabled")</tt> and of <tt>tr("Disabled")</tt> in PrintPanel. Since both "Enabled"s and "Disabled"s appear in the same context <em>TQt Linguist</em> will only display one occurrence of each and will use the same translations for the duplicates that it doesn't display. Whilst this is a useful timesaver, in some languages, such as Portuguese, the second occurrence requires a separate translation. We will see how <em>TQt Linguist</em> can be made to display all the occurrences for separate translation shortly.</p>
<!-- index MainWindow!in Translation Tutorial --><p>The header file for <tt>MainWindow</tt>, <tt>mainwindow.h</tt>, contains no surprises. In the implementation, <tt>mainwindow.cpp</tt>, we have some user-visible source texts that must be marked for translation.</p>
@ -1115,7 +1115,7 @@ proper behavior and even then QDockWindow does not limit stretchablilty.
<name>QDockWindow::newLine</name>
<doc href="qdockwindow.html#newLine-prop">
<p>This property holds whether the dock window prefers to start a new line in the dock area.
<p>The default is FALSE, i.e. the dock window doesn't retquire a new
<p>The default is FALSE, i.e. the dock window doesn't require a new
line in the dock area.
<p>Set this property's value with <a href="qdockwindow.html#setNewLine">setNewLine</a>() and get this property's value with <a href="qdockwindow.html#newLine">newLine</a>().
@ -2145,17 +2145,17 @@ arguments.
<p> The mask format understands these mask characters:
<tr bgcolor="#d0d0d0"> <td valign="top"><tt>a</tt> <td valign="top">ASCII alphabetic character permitted but not retquired.
<tr bgcolor="#d0d0d0"> <td valign="top"><tt>n</tt> <td valign="top">ASCII alphanumeric character permitted but not retquired.
<tr bgcolor="#f0f0f0"> <td valign="top"><tt>X</tt> <td valign="top">Any character retquired.
<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qwidget.html#x-prop">x</a> <td valign="top">Any character permitted but not retquired.
<tr bgcolor="#d0d0d0"> <td valign="top"><tt>d</tt> <td valign="top">ASCII digit permitted but not retquired (1-9).
<tr bgcolor="#f0f0f0"> <td valign="top"><tt>#</tt> <td valign="top">ASCII digit or plus/minus sign permitted but not retquired.
<tr bgcolor="#d0d0d0"> <td valign="top"><tt>a</tt> <td valign="top">ASCII alphabetic character permitted but not required.
<tr bgcolor="#d0d0d0"> <td valign="top"><tt>n</tt> <td valign="top">ASCII alphanumeric character permitted but not required.
<tr bgcolor="#f0f0f0"> <td valign="top"><tt>X</tt> <td valign="top">Any character required.
<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qwidget.html#x-prop">x</a> <td valign="top">Any character permitted but not required.
<tr bgcolor="#d0d0d0"> <td valign="top"><tt>d</tt> <td valign="top">ASCII digit permitted but not required (1-9).
<tr bgcolor="#f0f0f0"> <td valign="top"><tt>#</tt> <td valign="top">ASCII digit or plus/minus sign permitted but not required.
<tr bgcolor="#d0d0d0"> <td valign="top"><tt>&gt;</tt> <td valign="top">All following alphabetic characters are uppercased.
<tr bgcolor="#f0f0f0"> <td valign="top"><tt>&lt;</tt> <td valign="top">All following alphabetic characters are lowercased.
<tr bgcolor="#d0d0d0"> <td valign="top"><tt>!</tt> <td valign="top">Switch off case conversion.
("FIL" is the retquired spelling in Microsoft's API.)
("FIL" is the required spelling in Microsoft's API.)
<p> There is no default value.
<p>Set this property's value with <a href="qsqldatabase.html#setDatabaseName">setDatabaseName</a>() and get this property's value with <a href="qsqldatabase.html#databaseName">databaseName</a>().
@ -4374,7 +4374,7 @@ that the auto mask calculation works, you should add:
<p> at the end of your event handlers. This is true for all member
functions that change the appearance of the widget in a way that
retquires a recalculation of the mask.
requires a recalculation of the mask.
<p> While being a technically appealing concept, masks have a big
drawback: when using complex masks that cannot be expressed easily
with relatively simple regions, they can be very slow on some
<aname="1"></a><p> The TQAxServer module provides a static library implementing the
functions retquired to turn a standard TQt binary into an ActiveX
functions required to turn a standard TQt binary into an ActiveX
control server.
<p> This module is part of the <ahref="activeqt.html">ActiveTQt
framework</a>. (To incorporate ActiveX controls in a TQt
@ -195,7 +195,7 @@ You can modify these files as long as it includes any file as the
type library entry, ie. you can add version information or use a
different toolbox icon.
<p> The <tt>activeqt</tt> configuration will cause the <tt>qmake</tt> tool to add the
retquired build steps to the build system:
required build steps to the build system:
<ul>
<li> link the binary against <tt>qaxserver.lib</tt>
<li> generate an interface definition and link the type library into
@ -226,7 +226,7 @@ continue to run.
<p> An in-process server is usually smaller and has faster startup
time. The communication between client and server is done directly
through virtual function calls and does not introduce the overhead
retquired for remote procedure calls. But if the server crashes the
required for remote procedure calls. But if the server crashes the
client application is likely to crash as well.
<p> Both server types can use TQt either as a shared library, or
statically linked into the server binary.
@ -259,7 +259,7 @@ Microsoft Visual C++ 6.0 compiler.
<aname="4-1-1-1"></a><p> When the error occurs in code that uses the <ahref="qaxfactory.html#TQAXFACTORY_DEFAULT">TQAXFACTORY_DEFAULT</a>
macro, the widget class had no constructor that can be used by the
default factory. Either add a standard widget constructor or
implement a custom factory that doesn't retquire one.
implement a custom factory that doesn't require one.
<p> When the error occurs in code that uses the <ahref="qaxfactory.html#TQAXFACTORY_EXPORT">TQAXFACTORY_EXPORT</a>
macro, the <ahref="qaxfactory.html">TQAxFactory</a> subclass had no appropriate constructor.
Provide a public class constructor like
@ -304,18 +304,18 @@ of the binary to make it into an ActiveX server.
<li> Attach the type library as a binary resource to the server
<li> Register the server
</ul>
<p> For this to work the server has to meet some retquirements:
<p> For this to work the server has to meet some requirements:
<p><ul>
<li> All controls exposed can be created with nothing but a <ahref="qapplication.html">TQApplication</a>
instance being present
<li> The initial linking of the server includes a temporary type
library resource
<li> All dependencies retquired to run the server are in the system path
<li> All dependencies required to run the server are in the system path
(or in the path used by the calling environment; note that Visual
Studio has it's own set of environment variables listed in the
Tools|Options|Directories dialog).
</ul>
<p> If those retquirements are not met one ore more of the following
<p> If those requirements are not met one ore more of the following
errors are likely to occure:
<p><h5> The server executable crashes
</h5>
@ -341,7 +341,7 @@ the interface definition, and to register the server. If a dynamic
link library the server links against is not in the path this
might fail (e.g. Visual Studio calls the server using the
enivronment settings specified in the "Directories" option). Make
sure that all DLLs retquired by your server are located in a
sure that all DLLs required by your server are located in a
directory that is listed in the path as printed in the error
message box.
<p><h5> The Server does not respond
@ -386,7 +386,7 @@ or any existing TQWidget subclass:
<ahref="metaobjects.html#Q_OBJECT">Q_OBJECT</a>
</pre>
<p> The <ahref="metaobjects.html#Q_OBJECT">Q_OBJECT</a> macro is retquired to provide the <ahref="metaobjects.html#meta-object">meta object</a> information
<p> The <ahref="metaobjects.html#Q_OBJECT">Q_OBJECT</a> macro is required to provide the <ahref="metaobjects.html#meta-object">meta object</a> information
about the widget to the ActiveTQt framework.
Use the <tt>Q_PROPERTY</tt> macro to declare properties for the ActiveX control:
<p><pre>
@ -640,7 +640,7 @@ server must export an implementation of a <a href="qaxfactory.html">TQAxFactory<
default factory when the server provides only a single ActiveX
control, and implement a subclass of TQAxFactory to provide
multiple ActiveX controls. The default factory is available
through a macro that takes the identifiers COM retquires to locate
through a macro that takes the identifiers COM requires to locate
the ActiveX control on the target system:
<p><pre>
TQAXFACTORY_DEFAULT ( MyActiveX,
@ -734,7 +734,7 @@ make the server available to the browser used to view your page, and
you need to specify the location of the server package in your page.
<p> To specify the location of a server, use the CODEBASE attribute in
the OBJECT tag of your web-site. The value can point to the server
file itself, to an <tt>INF</tt> file listing other files the server retquires
file itself, to an <tt>INF</tt> file listing other files the server requires
(e.g. the TQt DLL), or a compressed <tt>CAB</tt> archive.
<p> INF and CAB files are documented in almost every book available about
ActiveX and COM programming as well as in the MSDN library and various
@ -873,8 +873,8 @@ Ie. the default property of a push button would be "text".
Ie. the default signal of a push button would be "clicked".
<trbgcolor="#f0f0f0">
<tdvalign="top">LicenseKey
<tdvalign="top">Object creation retquires the specified license key. The key can be
empty to retquire a licensed machine. By default classes are not
<tdvalign="top">Object creation requires the specified license key. The key can be
empty to require a licensed machine. By default classes are not
licensed. Also see the following section.
<trbgcolor="#d0d0d0">
<tdvalign="top">StockEvents
@ -951,14 +951,14 @@ macro.
};
</pre>
The key is retquired to be able to create an instance of <tt>MyLicensedControl</tt>
The key is required to be able to create an instance of <tt>MyLicensedControl</tt>
on a machine that is not licensed itself. The licensed developer can now
redistributes the server binary with his application, which creates the control
using the value of "LicenseKey", while users of the application cannot create
the control without the license key.
<p> If a single license key for the control is not sufficient (ie. you want
differnet developers to receive different license keys) you can specify an
empty key to indicate that the control retquires a license, and reimplement
empty key to indicate that the control requires a license, and reimplement
<ahref="qaxfactory.html#validateLicenseKey">TQAxFactory::validateLicenseKey</a>() to verify that a license exists on the
system (ie. through a license file).
<p><h3> More Interfaces
@ -1056,10 +1056,10 @@ Microsoft
OLE needs to marshal user defined types by reference (ByRef), and cannot
marshal them by value (ByVal). This is why const-references and object
parameters are not supported for <ahref="qrect.html">TQRect</a>, <ahref="qsize.html">TQSize</a> and <ahref="qpoint.html">TQPoint</a>. Also note that
servers with this datatype retquire Windows 98 or DCOM 1.2 to be installed.
servers with this datatype require Windows 98 or DCOM 1.2 to be installed.
@ -158,7 +158,7 @@ controlled with <a href="#setExtension">setExtension</a>(), <a href="#setOrienta
<h3> Return value (modal dialogs)
</h3>
<aname="1-5"></a><p> Modal dialogs are often used in situations where a return value is
retquired, e.g. to indicate whether the user pressed "OK" or
required, e.g. to indicate whether the user pressed "OK" or
"Cancel". A dialog can be closed by calling the <ahref="#accept">accept</a>() or the
<ahref="#reject">reject</a>() slots, and <ahref="#exec">exec</a>() will return <ahref="#DialogCode-enum">Accepted</a> or <ahref="#DialogCode-enum">Rejected</a>
as appropriate. The exec() call returns the result of the dialog.
@ -443,7 +443,7 @@ proper behavior and even then TQDockWindow does not limit stretchablilty.
<p>Set this property's value with <ahref="#setMovingEnabled">setMovingEnabled</a>() and get this property's value with <ahref="#isMovingEnabled">isMovingEnabled</a>().
@ -77,7 +77,7 @@ from the set of icons it is given. Such pixmaps are used by
<ahref="qtoolbutton.html">TQToolButton</a>, <ahref="qheader.html">TQHeader</a>, <ahref="qpopupmenu.html">TQPopupMenu</a>, etc. to show an icon representing a
particular action.
<p> The simplest use of TQIconSet is to create one from a <ahref="qpixmap.html">TQPixmap</a> and then
use it, allowing TQt to work out all the retquired icon styles and
use it, allowing TQt to work out all the required icon styles and
sizes. For example:
<p><pre>
<ahref="qtoolbutton.html">TQToolButton</a> *but = new <ahref="qtoolbutton.html">TQToolButton</a>( <ahref="#TQIconSet">TQIconSet</a>( TQPixmap("open.xpm") ), ... );
@ -174,7 +174,7 @@ pixel size. This is a useful default.
<li><tt>TQIconSet::Large</tt> - The pixmap is the larger of two.
</ul><p> If a Small pixmap is not set by <ahref="#setPixmap">TQIconSet::setPixmap</a>(), the Large
pixmap will be automatically scaled down to the size of a small pixmap
to generate the Small pixmap when retquired. Similarly, a Small pixmap
to generate the Small pixmap when required. Similarly, a Small pixmap
will be automatically scaled up to generate a Large pixmap. The
preferred sizes for large/small generated icons can be set using
<p><em>qmake</em> is a tool created by Trolltech to write makefiles for different compilers and platforms.</p>
<p>Writing makefiles by hand can be difficult and error prone, especially if several makefiles are retquired for different compiler and platform combinations. With <em>qmake</em>, developers create a simple single 'project' file and run <em>qmake</em> to generate the appropriate makefiles. <em>qmake</em> takes care of all the compiler and platform dependencies, freeing developers to focus on their code. Trolltech uses <em>qmake</em> as the primary build tool for the TQt library, and for the tools supplied with TQt.</p>
<p><em>qmake</em> also takes care of TQt's special retquirements, automatically including build rules for <ahref="moc.html">moc</a> and <em>uic</em>.</p>
<p>Writing makefiles by hand can be difficult and error prone, especially if several makefiles are required for different compiler and platform combinations. With <em>qmake</em>, developers create a simple single 'project' file and run <em>qmake</em> to generate the appropriate makefiles. <em>qmake</em> takes care of all the compiler and platform dependencies, freeing developers to focus on their code. Trolltech uses <em>qmake</em> as the primary build tool for the TQt library, and for the tools supplied with TQt.</p>
<p><em>qmake</em> also takes care of TQt's special requirements, automatically including build rules for <ahref="moc.html">moc</a> and <em>uic</em>.</p>
<p>This line specifies the source files that implement the application. In this case there is just one file, <em>hello.cpp</em>. Most applications retquire multiple files; this situation is dealt with by listing all the files on the same line space separated, like this:</p>
<p>This line specifies the source files that implement the application. In this case there is just one file, <em>hello.cpp</em>. Most applications require multiple files; this situation is dealt with by listing all the files on the same line space separated, like this:</p>
<p>Use <em>qmake</em> as before to generate a makefile. If you rename <em>main.cpp</em> temporarily, you will see the message and <em>qmake</em> will stop processing.</p>
<h3><aname="6"></a>Checking for more than one condition</h3>
<p>Suppose you use Windows and you want to be able to see the qDebug() statements when you run your application on the command line. Unless you build your application with the console setting, you won't see the output. We can easily put <em>console</em> on the CONFIG line so that on Windows the makefile will have this setting. But let's say that we only want to add the CONFIG line if we are running on Windows <em>and</em> when <em>debug</em> is already on the CONFIG line. This retquires using two nested scopes; just create one scope, then create the other inside that one. Put the settings to be processed inside the last scope, like this:</p>
<p>Suppose you use Windows and you want to be able to see the qDebug() statements when you run your application on the command line. Unless you build your application with the console setting, you won't see the output. We can easily put <em>console</em> on the CONFIG line so that on Windows the makefile will have this setting. But let's say that we only want to add the CONFIG line if we are running on Windows <em>and</em> when <em>debug</em> is already on the CONFIG line. This requires using two nested scopes; just create one scope, then create the other inside that one. Put the settings to be processed inside the last scope, like this:</p>
<p><em>qmake</em> is an easy-to-use tool from Trolltech that creates makefiles for development projects across different platforms. <em>qmake</em> simplifies the generation of makefiles so that only a few lines of information are needed to create a makefile. <em>qmake</em> can be used for any software project whether it is written in TQt or not, although it also contains additional features to support TQt development.</p>
<p><em>qmake</em> generates a makefile based on the information in a project file. Project files are created by the developer. Project files are usually simple, but can be quite sophisticated if retquired. <em>qmake</em> can also generate projects for Microsoft Visual studio without having to change the project file.</p>
<p><em>qmake</em> generates a makefile based on the information in a project file. Project files are created by the developer. Project files are usually simple, but can be quite sophisticated if required. <em>qmake</em> can also generate projects for Microsoft Visual studio without having to change the project file.</p>
<p>Before <em>qmake</em> can be used to build makefiles, the QMAKESPEC environment variable must be set to the platform-compiler combination that is being used on the system. The QMAKESPEC environment variable tells qmake where to look to find platform and compiler specific information. This ensures that the right libraries are used, and that the generated makefile uses the correct syntax. A list of the currently supported platform-compiler combinations can be found in qt/mkspecs. Just set your environment variable to one of the directories listed.</p>
<p>The second notation allows you to adjoin the variable expansion to another value without separating by space. <em>qmake</em> will allow a variable to contain anything (including $(VALUE), which will be placed directly into the Makefile, and allow it to expand as appropriate, usually an environment variable). However, if you retquire an environment variable to be replaced immediately then you may use the $$() notation. For example:</p>
<p>The second notation allows you to adjoin the variable expansion to another value without separating by space. <em>qmake</em> will allow a variable to contain anything (including $(VALUE), which will be placed directly into the Makefile, and allow it to expand as appropriate, usually an environment variable). However, if you require an environment variable to be replaced immediately then you may use the $$() notation. For example:</p>
<pre>
MY_DEFINES = $$(ENV_DEFINES)
</pre>
<p>This will set MY_DEFINES to the value of the evironment variable ENV_DEFINES as it parses the .pro file. Additionally you may call built-in functions in variable replacing. These functions (not to be confused with Test Functions as enumerated in the next section) are listed below:</p>
<h4><aname="4-1"></a>join( variablename, glue, before, after )</h4>
<p>This will join the value of <em>variablename</em> with glue. If this value is non-empty it will prefix the value with <em>before</em> and suffix it with <em>after</em>. <em>variablename</em> is the only retquired field, the others will default to empty strings. If you need to encode spaces in <em>glue</em>, <em>before</em>, or <em>after</em> you must quote them.</p>
<p>This will join the value of <em>variablename</em> with glue. If this value is non-empty it will prefix the value with <em>before</em> and suffix it with <em>after</em>. <em>variablename</em> is the only required field, the others will default to empty strings. If you need to encode spaces in <em>glue</em>, <em>before</em>, or <em>after</em> you must quote them.</p>
<h4><aname="4-2"></a>prompt( question )</h4>
<p>This will display <em>question</em>, and read from stdin as a return value.</p>
<h4><aname="4-3"></a>member( variablename, position )</h4>
<p>This will place the value in <em>variablename</em> in position <em>position</em> of the list. If the value of <em>variablename</em> is not long this will return an empty string. <em>variablename</em> is the only retquired field, if not specified position will default to the first value in the list (0).</p>
<p>This will place the value in <em>variablename</em> in position <em>position</em> of the list. If the value of <em>variablename</em> is not long this will return an empty string. <em>variablename</em> is the only required field, if not specified position will default to the first value in the list (0).</p>
<p>This will place all the values in <em>variablename</em> that match <em>substr</em>. <em>substr</em> may be a regular expression as well, and will be matched accordingly.</p>
<li><p>warn_on - The compiler should emit more warnings than normally, ignored if "warn_off" is specified</p>
<li><p>warn_off - The compiler should only emit severe warnings.</p>
</ul><p>These options define the application/library type:</p>
<ul><li><p>qt - The target is a TQt application/library and retquires the TQt header files/library. The proper include and library paths for the TQt library will automatically be added to the project.</p>
<li><p>opengl - The target retquires the OpenGL (or Mesa) headers/libraries. The proper include and library paths for these libraries will automatically be added to the project.</p>
<ul><li><p>qt - The target is a TQt application/library and requires the TQt header files/library. The proper include and library paths for the TQt library will automatically be added to the project.</p>
<li><p>opengl - The target requires the OpenGL (or Mesa) headers/libraries. The proper include and library paths for these libraries will automatically be added to the project.</p>
<li><p>thread - The target is a multi-threaded application or library. The proper defines and compiler flags will automatically be added to the project.</p>
<li><p>x11 - The target is a X11 application or library. The proper include paths and libraries will automatically be added to the project.</p>
<li><p>windows - The target is a Win32 window application (app only). The proper include paths,compiler flags and libraries will automatically be added to the project.</p>
@ -141,7 +141,7 @@ DEFINES += USE_MY_STUFF QT_DLL
<p>Specifies where to copy the <ahref="qmake-manual-8.html#TARGET">target</a> dll.</p>
<p><em>qmake</em> will generate dependency information (unless -nodepend is specified on the <ahref="qmake-manual-8.html#Commands">command line</a>) for the specified headers. <em>qmake</em> will also automatically detect if <em>moc</em> is retquired by the classes in these headers, and add the appropriate dependencies and files to the project for generating and linking the moc files.</p>
<p><em>qmake</em> will generate dependency information (unless -nodepend is specified on the <ahref="qmake-manual-8.html#Commands">command line</a>) for the specified headers. <em>qmake</em> will also automatically detect if <em>moc</em> is required by the classes in these headers, and add the appropriate dependencies and files to the project for generating and linking the moc files.</p>
<p>This variable specifies the .ui files (see <ahref="designer-manual.html">TQt Designer</a>) to be processed through <em>uic</em> before compiling. All dependencies, headers and source files retquired to build these .ui files will automatically be added to the project.</p>
<p>This variable specifies the .ui files (see <ahref="designer-manual.html">TQt Designer</a>) to be processed through <em>uic</em> before compiling. All dependencies, headers and source files required to build these .ui files will automatically be added to the project.</p>
<p>This variable indicates the header file for creating a precompiled header file, to increase the compilation speed of a project. Precompiled headers are currently only supported on some platforms (Windows - all MSVC project types, Mac OS X - Xcode, Makefile, UNIX - gcc 3.3 and up).</p>
<p>On other platforms, this variable has different meaning, as noted below.</p>
<p>This variable contains a list of header files that retquire some sort of pre-compilation step (such as with moc). The value of this variable is typically handled by <em>qmake</em> or <ahref="qmake-manual-8.html#QMAKESPEC">qmake.conf</a> and rarely needs to be modified.</p>
<p>This variable contains a list of header files that require some sort of pre-compilation step (such as with moc). The value of this variable is typically handled by <em>qmake</em> or <ahref="qmake-manual-8.html#QMAKESPEC">qmake.conf</a> and rarely needs to be modified.</p>
<p>This variable contains the name of the <em>qmake</em> program itself and is placed in generated makefiles. The value of this variable is typically handled by <em>qmake</em> or <ahref="qmake-manual-8.html#QMAKESPEC">qmake.conf</a> and rarely needs to be modified.</p>
<p>This variable contains the extention for shared libraries. The value of this variable is typically handled by <em>qmake</em> or <ahref="qmake-manual-8.html#QMAKESPEC">qmake.conf</a> and rarely needs to be modified.</p>
<p>This variable contains the list of retquirements that were failed to be met when <em>qmake</em> was used. For example, the sql module is needed and wasn't compiled into TQt. The value of this variable is typically handled by <em>qmake</em> or <ahref="qmake-manual-8.html#QMAKESPEC">qmake.conf</a> and rarely needs to be modified.</p>
<p>This variable contains the list of requirements that were failed to be met when <em>qmake</em> was used. For example, the sql module is needed and wasn't compiled into TQt. The value of this variable is typically handled by <em>qmake</em> or <ahref="qmake-manual-8.html#QMAKESPEC">qmake.conf</a> and rarely needs to be modified.</p>
<p>This variable contains the file tags needed to be entered into the makefile, such as SOURCES and HEADERS. The value of this variable is typically handled by <em>qmake</em> or <ahref="qmake-manual-8.html#QMAKESPEC">qmake.conf</a> and rarely needs to be modified.</p>
<p><em>qmake</em> retquires a platform and compiler description file which contains many default values used to generate appropriate makefiles. The standard TQt distribution comes with many of these files, located in the 'mkspecs' subdirectory of the TQt installation.</p>
<p><em>qmake</em> requires a platform and compiler description file which contains many default values used to generate appropriate makefiles. The standard TQt distribution comes with many of these files, located in the 'mkspecs' subdirectory of the TQt installation.</p>
<p>The QMAKESPEC environment variable can contain any of the following:</p>
<ul><li><p>A complete path to a directory containing a qmake.conf file. In this case <em>qmake</em> will open the qmake.conf file from within that directory. If the file does not exist, <em>qmake</em> will exit with an error.</p>
<li><p>The name of a platform-compiler combination. In this case, <em>qmake</em> will search in the directory specified by the QTDIR environment variable.</p>
@ -657,7 +657,7 @@ QMAKE_VERS = $$[QMAKE_VERSION]
<pre>
INSTALLS += documentation
</pre>
<p>Now <em>qmake</em> will take over making sure the correct things are copied to the specified places. If however you retquire greater control you may use the 'extra' member of the object:</p>
<p>Now <em>qmake</em> will take over making sure the correct things are copied to the specified places. If however you require greater control you may use the 'extra' member of the object:</p>
<p>The cache file (mentioned above in the options) is a special file <em>qmake</em> will read to find settings not specified in the <tt>qmake.conf</tt> file, the .pro file, or the command line. If <tt>-nocache</tt> is not specified, <em>qmake</em> will try to find a file called <tt>.qmake.cache</tt> in parent directories. If it fails to find this file, it will silently ignore this step of processing.</p>
<p>Often when linking against a library <em>qmake</em> relies on the underlying platform to know what other libraries this library links against, and lets the platform pull them in. In many cases, however, this is not sufficent. For example when statically linking a library there are no libraries linked against, and therefore no dependencies to those libraries are created - however an application that later links against this library will need to know where to find the symbols that the linked in library will retquire. To help with this situation <em>qmake</em> will follow a library's dependencies when it feels appropriate, however this behaviour must be enabled in <em>qmake</em>. To enable retquires two steps. First, you must enable it in the library - to do this you must tell <em>qmake</em> to save information about this library:</p>
<p>Often when linking against a library <em>qmake</em> relies on the underlying platform to know what other libraries this library links against, and lets the platform pull them in. In many cases, however, this is not sufficent. For example when statically linking a library there are no libraries linked against, and therefore no dependencies to those libraries are created - however an application that later links against this library will need to know where to find the symbols that the linked in library will require. To help with this situation <em>qmake</em> will follow a library's dependencies when it feels appropriate, however this behaviour must be enabled in <em>qmake</em>. To enable requires two steps. First, you must enable it in the library - to do this you must tell <em>qmake</em> to save information about this library:</p>
@ -501,7 +501,7 @@ printed with the corresponding <a href="#drawText">drawText</a>() function using
<em>len</em> characters from <em>str</em> if <em>len</em> is > -1, or the whole of
<em>str</em> if <em>len</em> is -1. The drawing, and hence the bounding
rectangle, is constrained to the rectangle <em>r</em>, or to the
rectangle retquired to draw the text, whichever is the larger.
rectangle required to draw the text, whichever is the larger.
<p> The <em>internal</em> parameter should not be used.
<p><p>See also <ahref="#drawText">drawText</a>(), <ahref="#fontMetrics">fontMetrics</a>(), <ahref="qfontmetrics.html#boundingRect">TQFontMetrics::boundingRect</a>(), and <ahref="qt.html#TextFlags-enum">TQt::TextFlags</a>.
@ -548,7 +548,7 @@ Writes the boolean entry <em>value</em> into key <em>key</em>. The <em>key</em>
created if it doesn't exist. Any previous value is overwritten by <em>value</em>.
<p> If an error occurs the settings are left unchanged and FALSE is
returned; otherwise TRUE is returned.
<p><b>Warning:</b> On certain platforms, keys are retquired to contain at least
<p><b>Warning:</b> On certain platforms, keys are required to contain at least
two components (e.g., "/foo/bar"). This limitation does not apply to
TQt 4.
<p><p>See also <ahref="#readListEntry">readListEntry</a>(), <ahref="#readNumEntry">readNumEntry</a>(), <ahref="#readDoubleEntry">readDoubleEntry</a>(), <ahref="#readBoolEntry">readBoolEntry</a>(), and <ahref="#removeEntry">removeEntry</a>().
("FIL" is the retquired spelling in Microsoft's API.)
("FIL" is the required spelling in Microsoft's API.)
<p> There is no default value.
<p>Set this property's value with <ahref="#setDatabaseName">setDatabaseName</a>() and get this property's value with <ahref="#databaseName">databaseName</a>().
@ -1044,7 +1044,7 @@ checkable by default (<a href="qpopupmenu.html#setCheckable">TQPopupMenu::setChe
<p> Returns the SubControl for <em>widget</em> at the point <em>pos</em>. The <em>widget</em> argument is a pointer to a <ahref="qwidget.html">TQWidget</a> or one of its
subclasses. The widget can be cast to the appropriate type based
on the value of <em>control</em>. The <em>opt</em> argument can be used to
pass extra information retquired when drawing the ComplexControl.
pass extra information required when drawing the ComplexControl.
Note that <em>opt</em> may be the default value even for ComplexControls
that can make use of the extra options. See <ahref="#drawComplexControl">drawComplexControl</a>()
for an explanation of the <em>widget</em> and <em>opt</em> arguments.
@ -1062,7 +1062,7 @@ logical coordinates.
<p> The <em>widget</em> argument is a pointer to a <ahref="qwidget.html">TQWidget</a> or one of its
subclasses. The widget can be cast to the appropriate type based
on the value of <em>control</em>. The <em>opt</em> argument can be used to
pass extra information retquired when drawing the ComplexControl.
pass extra information required when drawing the ComplexControl.
Note that <em>opt</em> may be the default value even for ComplexControls
that can make use of the extra options. See <ahref="#drawComplexControl">drawComplexControl</a>()
for an explanation of the <em>widget</em> and <em>opt</em> arguments.
@ -1080,7 +1080,7 @@ for an explanation of the <em>widget</em> and <em>opt</em> arguments.
<p> The <em>widget</em> argument is a pointer to a <ahref="qwidget.html">TQWidget</a> or one of its
subclasses. The widget can be cast to the appropriate type based
on the value of <em>contents</em>. The <em>opt</em> argument can be used to
pass extra information retquired when calculating the size. Note
pass extra information required when calculating the size. Note
that <em>opt</em> may be the default value even for ContentsTypes that
can make use of the extra options. See the table below for the
appropriate <em>widget</em> and <em>opt</em> usage:
@ -1114,7 +1114,7 @@ allow for future enhancements.
</h3>
<p> Returns a pixmap for <em>stylepixmap</em>.
<p> The <em>opt</em> argument can be used to pass extra information retquired
<p> The <em>opt</em> argument can be used to pass extra information required
when drawing the ControlElement. Note that <em>opt</em> may be the
default value even for StylePixmaps that can make use of the extra
options. Currently, the <em>opt</em> argument is unused.
<p> TQValueVector stores its elements in contiguous memory. This means
that you can use a TQValueVector in any situation that retquires an
that you can use a TQValueVector in any situation that requires an
array.
<p>See also <ahref="qtl.html">TQt Template Library Classes</a>, <ahref="shared.html">Implicitly and Explicitly Shared Classes</a>, and <ahref="tools.html">Non-GUI Classes</a>.
This overview assumes that you have at least a basic knowledge of SQL.
You should be able to understand simple <tt>SELECT</tt>, <tt>INSERT</tt>, <tt>UPDATE</tt>
and <tt>DELETE</tt> commands. Although the <ahref="qsqlcursor.html">TQSqlCursor</a> class provides an
interface to database browsing and editing that does not <em>retquire</em> a
interface to database browsing and editing that does not <em>require</em> a
knowledge of SQL, a basic understanding of SQL is highly recommended. A
standard text covering SQL databases is <em>An Introduction to Database Systems (7th ed.)</em> by C. J. Date, ISBN 0201385902.
</blockquote>
@ -222,9 +222,9 @@ for more information).
<aname="4"></a><p> At least one database connection must be created and opened before the
<ahref="qsqlquery.html">TQSqlQuery</a> or <ahref="qsqlcursor.html">TQSqlCursor</a> classes can be used.
<p> If the application only needs a single database connection, the <ahref="qsqldatabase.html">TQSqlDatabase</a> class can create a connection which is used by default
for all SQL operations. If multiple database connections are retquired
for all SQL operations. If multiple database connections are required
these can easily be set up.
<p><ahref="qsqldatabase.html">TQSqlDatabase</a> retquires the <ahref="qsqldatabase-h.html">qsqldatabase.h</a> header file.
<p><ahref="qsqldatabase.html">TQSqlDatabase</a> requires the <ahref="qsqldatabase-h.html">qsqldatabase.h</a> header file.
<p><aname="Connecting_to_a_Single_Database"></a>
<h2> Connecting to a Single Database
</h2>
@ -622,7 +622,7 @@ presented earlier.
follows this one we show how to link widgets to database cursors. Once
we have a knowledge of both cursors and data-aware widgets we can
</pre><blockquote><palign="center"><em> From <ahref="sql-overview-table1-main-cpp.html">sql/overview/table1/main.cpp</a>
</em></p>
</blockquote><p> Data-Aware tables retquire the <ahref="qdatatable-h.html">qdatatable.h</a> and <ahref="qsqlcursor-h.html">qsqlcursor.h</a> header
</blockquote><p> Data-Aware tables require the <ahref="qdatatable-h.html">qdatatable.h</a> and <ahref="qsqlcursor-h.html">qsqlcursor.h</a> header
files. We create our application object, call createConnections() and
create the cursor. We create the <ahref="qdatatable.html">TQDataTable</a> passing it a pointer to
the cursor, and set the autoPopulate flag to TRUE. Next we make our <ahref="qdatatable.html">TQDataTable</a> the main widget and call refresh() to populate it with data
@ -1370,7 +1370,7 @@ leave the loop.
<p> When the user edits the status field in the <ahref="qdatatable.html">TQDataTable</a> they will be
presented with a combobox of valid status names taken from the status
table. However the status displayed is still the raw statusid. To
display the status name when the field isn't being edited retquires us
display the status name when the field isn't being edited requires us
to subclass TQDataTable and reimplement the paintField() function.
<p>
@ -1487,7 +1487,7 @@ name of the table. We don't have any other characteristics to add at
this stage.
<p><pre> InvoiceItemCursor invoiceItemCursor;
</pre>
<p> Whenever we retquire a cursor over the invoiceitem table we can create
<p> Whenever we require a cursor over the invoiceitem table we can create
an InvoiceItemCursor instead of a generic TQSqlCursor.
<p> We still need to show the product name rather than the pricesid.
<p>
@ -1541,7 +1541,7 @@ name.
which perform real calculations.
<p> The header file, <ahref="sql-overview-subclass4-main-h.html">sql/overview/subclass4/main.h</a>, remains unchanged
from the previous example, but the constructor and calculateField()
function retquire some simple expansion. We'll look at each in turn.
function require some simple expansion. We'll look at each in turn.
<p> Our implementation of the operators retquires the inclusion of <ahref="qtextstream-h.html">qtextstream.h</a> and <ahref="qstringlist-h.html">qstringlist.h</a>.
<p> Our implementation of the operators requires the inclusion of <ahref="qtextstream-h.html">qtextstream.h</a> and <ahref="qstringlist-h.html">qstringlist.h</a>.
(namespace processing, implies <em>http://xml.org/sax/features/namespace-prefixes</em>) and <em>http://xml.org/sax/features/validation</em> (the ability to report
validation errors).
<p> Whilst SAX2 leaves it to the user to define and implement whatever
features are retquired, support for <em>http://xml.org/sax/features/namespace</em> (and thus <em>http://xml.org/sax/features/namespace-prefixes</em>) is mandantory.
features are required, support for <em>http://xml.org/sax/features/namespace</em> (and thus <em>http://xml.org/sax/features/namespace-prefixes</em>) is mandantory.
The <ahref="qxmlsimplereader.html">TQXmlSimpleReader</a> implementation of <ahref="qxmlreader.html">TQXmlReader</a>,
supports them, and can do namespace processing.
<p><ahref="qxmlsimplereader.html">TQXmlSimpleReader</a> is not validating, so it
@ -340,7 +340,7 @@ must take care that they pass the right type. Properties are
useful if a reader supports special handler classes.
<p> The URIs used for features and properties often look like URLs, e.g.
<ahref="http://xml.org/sax/features/namespace">http://xml.org/sax/features/namespace</a>. This does not mean that the
data retquired is at this address. It is simply a way of defining
data required is at this address. It is simply a way of defining
unique names.
<p> Anyone can define and use new SAX2 properties for their readers.
Property support is not mandatory.
@ -556,7 +556,7 @@ is the part to the left of the ":". (<em>book</em> is the namespace prefix in
local part of <em>book:title</em>.)
<li> The <em>namespace URI</em> ("Uniform Resource Identifier") is a unique
identifier for a namespace. It looks like a URL
(e.g. <em>http://trolltech.com/fnord/</em> ) but does not retquire
(e.g. <em>http://trolltech.com/fnord/</em> ) but does not require
data to be accessible by the given protocol at the named address.
</ul>
<p> Elements without a ":" (like <em>chapter</em> in the example) do not have a
Returns the text cursor's flash (blink) time in milliseconds. The flash time is the time retquired to display, invert and restore the caret display.
Returns the text cursor's flash (blink) time in milliseconds. The flash time is the time required to display, invert and restore the caret display.
.PP
The default value on X11 is 1000 milliseconds. On Windows, the control panel value is used.
.PP
@ -1258,7 +1258,7 @@ QApplication::NormalColor. This is the default color allocation strategy. Use th
.TP
QApplication::CustomColor. Use this option if your application needs a small number of custom colors. On X11, this option is the same as NormalColor. On Windows, Qt creates a Windows palette, and allocates colors to it on demand.
.TP
QApplication::ManyColor. Use this option if your application is very color hungry (e.g. it retquires thousands of colors). Under X11 the effect is:
QApplication::ManyColor. Use this option if your application is very color hungry (e.g. it requires thousands of colors). Under X11 the effect is:
.TP
For 256-color displays which have at best a 256 color true color visual, the default visual is used, and colors are allocated from a color cube. The color cube is the 6x6x6 (216 color) "Web palette"<sup>*</sup>, but the number of colors can be changed by the \fI-ncols\fR option. The user can force the application to use the true color visual with the -visual option.
.TP
@ -1295,7 +1295,7 @@ See also colorSpec(), QColor::numBitPlanes(), and QColor::enterAllocContext().
Examples:
.)l helpviewer/main.cpp, opengl/main.cpp, showimg/main.cpp, t9/main.cpp, tetrax/tetrax.cpp, tetrix/tetrix.cpp, and themes/main.cpp.
.SH "void QApplication::setCursorFlashTime ( int msecs )\fC [static]\fR"
Sets the text cursor's flash (blink) time to \fImsecs\fR milliseconds. The flash time is the time retquired to display, invert and restore the caret display. Usually the text cursor is displayed for \fImsecs/2\fR milliseconds, then hidden for \fImsecs/2\fR milliseconds, but this may vary.
Sets the text cursor's flash (blink) time to \fImsecs\fR milliseconds. The flash time is the time required to display, invert and restore the caret display. Usually the text cursor is displayed for \fImsecs/2\fR milliseconds, then hidden for \fImsecs/2\fR milliseconds, but this may vary.
.PP
Note that on Microsoft Windows, calling this function sets the cursor flash time for all windows.
.PP
@ -1451,7 +1451,7 @@ See also QWidget::palette, palette(), and QStyle::polish().
Examples:
.)l i18n/main.cpp, themes/metal.cpp, themes/themes.cpp, and themes/wood.cpp.
.SH "void QApplication::setReverseLayout ( bool b )\fC [static]\fR"
If \fIb\fR is TRUE, all dialogs and widgets will be laid out in a mirrored fashion, as retquired by right to left languages such as Arabic and Hebrew. If \fIb\fR is FALSE, dialogs and widgets are laid out left to right.
If \fIb\fR is TRUE, all dialogs and widgets will be laid out in a mirrored fashion, as required by right to left languages such as Arabic and Hebrew. If \fIb\fR is FALSE, dialogs and widgets are laid out left to right.
.PP
Changing this flag in runtime does not cause a relayout of already instantiated widgets.
@ -63,7 +63,7 @@ The QAssistantClient class provides a means of using Qt Assistant as an applicat
.PP
Using Qt Assistant is simple: Create a QAssistantClient instance, then call showPage() as often as necessary to show your help pages. When you call showPage(), Qt Assistant will be launched if it isn't already running.
.PP
The QAssistantClient instance can open (openAssistant()) or close (closeAssistant()) Qt Assistant whenever retquired. If Qt Assistant is open, isOpen() returns TRUE.
The QAssistantClient instance can open (openAssistant()) or close (closeAssistant()) Qt Assistant whenever required. If Qt Assistant is open, isOpen() returns TRUE.
.PP
One QAssistantClient instance interacts with one Qt Assistant instance, so every time you call openAssistant(), showPage() or closeAssistant() they are applied to the particular Qt Assistant instance associated with the QAssistantClient.
@ -263,7 +263,7 @@ If you reimplement this function you must also reimplement the destructor to cal
.SH "QString QAxBase::control () const"
Returns the name of the COM object wrapped by this QAxBase object. See the "control" property for details.
.SH "void QAxBase::disableClassInfo ()"
Disables the class info generation for this ActiveX container. If you don't retquire any class information about the ActiveX control use this function to speed up the meta object generation.
Disables the class info generation for this ActiveX container. If you don't require any class information about the ActiveX control use this function to speed up the meta object generation.
.PP
Note that this function must be called immediately after construction of the object (without passing an object identifier), and before calling QAxWidget->setControl().
@ -48,7 +48,7 @@ This class is defined in the \fBQt ActiveQt Extension\fR, which can be found in
.PP
The QAxBindable class provides an interface between a QWidget and an ActiveX client.
.PP
The functions provided by this class allow an ActiveX control to communicate property changes to a client application. Inherit your control class from both QWidget (directly or indirectly) and this class to get access to this class's functions. The meta object compiler retquires you to inherit from QWidget \fIfirst\fR.
The functions provided by this class allow an ActiveX control to communicate property changes to a client application. Inherit your control class from both QWidget (directly or indirectly) and this class to get access to this class's functions. The meta object compiler requires you to inherit from QWidget \fIfirst\fR.
@ -106,7 +106,7 @@ Because QBitArray is a QMemArray, it uses explicit sharing with a reference coun
.PP
A QBitArray is a special byte array that can access individual bits and perform bit-operations (AND, OR, XOR and NOT) on entire arrays or bits.
.PP
Bits can be manipulated by the setBit() and clearBit() functions, but it is also possible to use the indexing [] operator to test and set individual bits. The [] operator is a little slower than setBit() and clearBit() because some tricks are retquired to implement single-bit assignments.
Bits can be manipulated by the setBit() and clearBit() functions, but it is also possible to use the indexing [] operator to test and set individual bits. The [] operator is a little slower than setBit() and clearBit() because some tricks are required to implement single-bit assignments.
Moves all QCanvasItem::animated() canvas items on the canvas and refreshes all changes to all views of the canvas. (An `animated' item is an item that is in motion; see setVelocity().)
.PP
The advance takes place in two phases. In phase 0, the QCanvasItem::advance() function of each QCanvasItem::animated() canvas item is called with paramater 0. Then all these canvas items are called again, with parameter 1. In phase 0, the canvas items should not change position, merely examine other items on the canvas for which special processing is retquired, such as collisions between items. In phase 1, all canvas items should change positions, ignoring any other items on the canvas. This two-phase approach allows for considerations of "fairness", although no QCanvasItem subclasses supplied with Qt do anything interesting in phase 0.
The advance takes place in two phases. In phase 0, the QCanvasItem::advance() function of each QCanvasItem::animated() canvas item is called with paramater 0. Then all these canvas items are called again, with parameter 1. In phase 0, the canvas items should not change position, merely examine other items on the canvas for which special processing is required, such as collisions between items. In phase 1, all canvas items should change positions, ignoring any other items on the canvas. This two-phase approach allows for considerations of "fairness", although no QCanvasItem subclasses supplied with Qt do anything interesting in phase 0.
.PP
The canvas can be configured to call this function periodically with setAdvancePeriod().
.PP
@ -331,7 +331,7 @@ This signal is emitted whenever the canvas is resized. Each QCanvasView connects
.SH "void QCanvas::retune ( int chunksze, int mxclusters = 100 )\fC [virtual]\fR"
Change the efficiency tuning parameters to \fImxclusters\fR clusters, each of size \fIchunksze\fR. This is a slow operation if there are many objects on the canvas.
.PP
The canvas is divided into chunks which are rectangular areas \fIchunksze\fR wide by \fIchunksze\fR high. Use a chunk size which is about the average size of the canvas items. If you choose a chunk size which is too small it will increase the amount of calculation retquired when drawing since each change will affect many chunks. If you choose a chunk size which is too large the amount of drawing retquired will increase because for each change, a lot of drawing will be retquired since there will be many (unchanged) canvas items which are in the same chunk as the changed canvas items.
The canvas is divided into chunks which are rectangular areas \fIchunksze\fR wide by \fIchunksze\fR high. Use a chunk size which is about the average size of the canvas items. If you choose a chunk size which is too small it will increase the amount of calculation required when drawing since each change will affect many chunks. If you choose a chunk size which is too large the amount of drawing required will increase because for each change, a lot of drawing will be required since there will be many (unchanged) canvas items which are in the same chunk as the changed canvas items.
.PP
Internally, a canvas uses a low-resolution "chunk matrix" to keep track of all the items in the canvas. A 64x64 chunk matrix is the default for a 1024x1024 pixel canvas, where each chunk collects canvas items in a 16x16 pixel square. This default is also affected by setTiles(). You can tune this default using this function. For example if you have a very large canvas and want to trade off speed for memory then you might set the chunk size to 32 or 64.
@ -74,7 +74,7 @@ The QCanvasPolygonalItem class provides a polygonal canvas item on a QCanvas.
.PP
The mostly rectangular classes, such as QCanvasSprite and QCanvasText, use the object's bounding rectangle for movement, repainting and collision calculations. For most other items, the bounding rectangle can be far too large -- a diagonal line being the worst case, and there are many other cases which are also bad. QCanvasPolygonalItem provides polygon-based bounding rectangle handling, etc., which is much faster for non-rectangular items.
.PP
Derived classes should try to define as small an area as possible to maximize efficiency, but the polygon must \fIdefinitely\fR be contained completely within the polygonal area. Calculating the exact retquirements is usually difficult, but if you allow a small overestimate it can be easy and tquick, while still getting almost all of QCanvasPolygonalItem's speed.
Derived classes should try to define as small an area as possible to maximize efficiency, but the polygon must \fIdefinitely\fR be contained completely within the polygonal area. Calculating the exact requirements is usually difficult, but if you allow a small overestimate it can be easy and tquick, while still getting almost all of QCanvasPolygonalItem's speed.
.PP
Note that all subclasses \fImust\fR call hide() in their destructor since hide() needs to be able to access areaPoints().
If \fIclose\fR is TRUE, then the first point in \fIctrl\fR will be re-used as the last point, and the number of control points must be a multiple of 3. If \fIclose\fR is FALSE, one additional control point is retquired, and the number of control points must be one of (4, 7, 10, 13, ...).
If \fIclose\fR is TRUE, then the first point in \fIctrl\fR will be re-used as the last point, and the number of control points must be a multiple of 3. If \fIclose\fR is FALSE, one additional control point is required, and the number of control points must be one of (4, 7, 10, 13, ...).
.PP
If the number of control points doesn't meet the above conditions, the number of points will be truncated to the largest number of points that do meet the retquirement.
If the number of control points doesn't meet the above conditions, the number of points will be truncated to the largest number of points that do meet the requirement.
This example assumes that the \fImsg\fR is a DCOP-style function signature and the \fIdata\fR contains the function's arguments. (See send().)
.PP
Using the DCOP convention is a recommendation, but not a retquirement. Whatever convention you use the sender and receiver \fImust\fR agree on the argument types.
Using the DCOP convention is a recommendation, but not a requirement. Whatever convention you use the sender and receiver \fImust\fR agree on the argument types.
Here the channel is "System/Shell". The \fImsg\fR is an arbitrary string, but in the example we've used the DCOP convention of passing a function signature. Such a signature is formatted as functionname(types) where types is a list of zero or more comma-separated type names, with no whitespace, no consts and no pointer or reference marks, i.e. no "*" or "&".
.PP
Using the DCOP convention is a recommendation, but not a retquirement. Whatever convention you use the sender and receiver \fImust\fR agree on the argument types.
Using the DCOP convention is a recommendation, but not a requirement. Whatever convention you use the sender and receiver \fImust\fR agree on the argument types.
You can select which byte order to use when serializing data. The default setting is big endian (MSB first). Changing it to little endian breaks the portability (unless the reader also changes to little endian). We recommend keeping this setting unless you have special retquirements.
You can select which byte order to use when serializing data. The default setting is big endian (MSB first). Changing it to little endian breaks the portability (unless the reader also changes to little endian). We recommend keeping this setting unless you have special requirements.
.SH "Reading and writing raw binary data"
You may wish to read/write your own raw binary data to/from the data stream directly. Data may be read from the stream into a preallocated char* using readRawBytes(). Similarly data can be written to the stream using writeRawBytes(). Notice that any encoding/decoding of the data must be done by you.
.PP
@ -488,7 +488,7 @@ Sets the serialization byte order to \fIbo\fR.
.PP
The \fIbo\fR parameter can be QDataStream::BigEndian or QDataStream::LittleEndian.
.PP
The default setting is big endian. We recommend leaving this setting unless you have special retquirements.
The default setting is big endian. We recommend leaving this setting unless you have special requirements.
.PP
See also byteOrder().
.SH "void QDataStream::setDevice ( QIODevice * d )"
@ -116,7 +116,7 @@ If the user presses the Esc key in a dialog, QDialog::reject() will be called. T
.SH "Extensibility"
Extensibility is the ability to show the dialog in two ways: a partial dialog that shows the most commonly used options, and a full dialog that shows all the options. Typically an extensible dialog will initially appear as a partial dialog, but with a" More" toggle button. If the user presses the "More" button down, the full dialog will appear. The extension widget will be resized to its sizeHint(). If orientation is Horizontal the extension widget's height() will be expanded to the height() of the dialog. If the orientation is Vertical the extension widget's width() will be expanded to the width() of the dialog. Extensibility is controlled with setExtension(), setOrientation() and showExtension().
.SH "Return value (modal dialogs)"
Modal dialogs are often used in situations where a return value is retquired, e.g. to indicate whether the user pressed "OK" or" Cancel". A dialog can be closed by calling the accept() or the reject() slots, and exec() will return Accepted or Rejected as appropriate. The exec() call returns the result of the dialog. The result is also available from result() if the dialog has not been destroyed. If the WDestructiveClose flag is set, the dialog is deleted after exec() returns.
Modal dialogs are often used in situations where a return value is required, e.g. to indicate whether the user pressed "OK" or" Cancel". A dialog can be closed by calling the accept() or the reject() slots, and exec() will return Accepted or Rejected as appropriate. The exec() call returns the result of the dialog. The result is also available from result() if the dialog has not been destroyed. If the WDestructiveClose flag is set, the dialog is deleted after exec() returns.
This function parses the XML document from the byte array \fIbuffer\fR and sets it as the content of the document. It tries to detect the encoding of the document as retquired by the XML specification.
This function parses the XML document from the byte array \fIbuffer\fR and sets it as the content of the document. It tries to detect the encoding of the document as required by the XML specification.
.PP
If \fInamespaceProcessing\fR is TRUE, the parser recognizes namespaces in the XML file and sets the prefix name, local name and namespace URI to appropriate values. If \fInamespaceProcessing\fR is FALSE, the parser does no namespace processing when it reads the XML file.
@ -46,7 +46,7 @@ All the functions in this class are reentrant when Qt is built with thread suppo
.SH DESCRIPTION
The QDomNodeList class is a list of QDomNode objects.
.PP
Lists can be obtained by QDomDocument::elementsByTagName() and QDomNode::childNodes(). The Document Object Model (DOM) retquires these lists to be "live": whenever you change the underlying document, the contents of the list will get updated.
Lists can be obtained by QDomDocument::elementsByTagName() and QDomNode::childNodes(). The Document Object Model (DOM) requires these lists to be "live": whenever you change the underlying document, the contents of the list will get updated.
.PP
You can get a particular node from the list with item(). The number of items in the list is returned by count() (and by length()).
@ -679,7 +679,7 @@ See also pointSize(), setPointSizeFloat(), pixelSize(), QFontInfo::pointSize(),
.SH "void QFont::qwsRenderToDisk ( bool all = TRUE )"
Saves the glyphs in the font that have previously been accessed as a QPF file. If \fIall\fR is TRUE (the default), then before saving, all glyphs are marked as used.
.PP
If the font is large and you are sure that only a subset of characters will ever be retquired on the target device, passing FALSE for the \fIall\fR parameter can save a significant amount of disk space.
If the font is large and you are sure that only a subset of characters will ever be required on the target device, passing FALSE for the \fIall\fR parameter can save a significant amount of disk space.
.PP
Note that this function is only applicable on Qt/Embedded.
\fBMac only\fR: This virtual function tries to find a visual that matches the format using the given \fIdevice\fR handle, reducing the demands if the original request cannot be met.
.PP
The algorithm for reducing the demands of the format is quite simple-minded, so override this method in your subclass if your application has specific retquirements on visual selection.
The algorithm for reducing the demands of the format is quite simple-minded, so override this method in your subclass if your application has specific requirements on visual selection.
\fBX11 only\fR: This virtual function tries to find a visual that matches the format, reducing the demands if the original request cannot be met.
.PP
The algorithm for reducing the demands of the format is quite simple-minded, so override this method in your subclass if your application has spcific retquirements on visual selection.
The algorithm for reducing the demands of the format is quite simple-minded, so override this method in your subclass if your application has spcific requirements on visual selection.
This virtual function is called once before the first call to paintGL() or resizeGL(), and then once whenever the widget has been assigned a new QGLContext. Reimplement it in a subclass.
.PP
This function should set up any retquired OpenGL context rendering flags, defining display lists, etc.
This function should set up any required OpenGL context rendering flags, defining display lists, etc.
.PP
There is no need to call makeCurrent() because this has already been done when this function is called.
This virtual function is used in the same manner as initializeGL() except that it operates on the widget's overlay context instead of the widget's main context. This means that initializeOverlayGL() is called once before the first call to paintOverlayGL() or resizeOverlayGL(). Reimplement it in a subclass.
.PP
This function should set up any retquired OpenGL context rendering flags, defining display lists, etc. for the overlay context.
This function should set up any required OpenGL context rendering flags, defining display lists, etc. for the overlay context.
.PP
There is no need to call makeOverlayCurrent() because this has already been done when this function is called.
@ -85,7 +85,7 @@ The functions and operators available with a QGuardedPtr are the same as those a
.PP
For creating guarded pointers, you can construct or assign to them from an X* or from another guarded pointer of the same type. You can compare them with each other using operator==() and operator!=(), or test for 0 with isNull(). And you can dereference them using either the \fC*x\fR or the \fCx->member\fR notation.
.PP
A guarded pointer will automatically cast to an X*, so you can freely mix guarded and unguarded pointers. This means that if you have a QGuardedPtr<QWidget>, you can pass it to a function that retquires a QWidget*. For this reason, it is of little value to declare functions to take a QGuardedPtr as a parameter; just use normal pointers. Use a QGuardedPtr when you are storing a pointer over time.
A guarded pointer will automatically cast to an X*, so you can freely mix guarded and unguarded pointers. This means that if you have a QGuardedPtr<QWidget>, you can pass it to a function that requires a QWidget*. For this reason, it is of little value to declare functions to take a QGuardedPtr as a parameter; just use normal pointers. Use a QGuardedPtr when you are storing a pointer over time.
.PP
Note again that class \fIX\fR must inherit QObject, or a compilation or link error will result.
.PP
@ -104,7 +104,7 @@ Destroys the guarded pointer. Just like a normal pointer, destroying a guarded p
.SH "bool QGuardedPtr::isNull () const"
Returns \fCTRUE\fR if the referenced object has been destroyed or if there is no referenced object; otherwise returns FALSE.
.SH "QGuardedPtr::operator T * () const"
Cast operator; implements pointer semantics. Because of this function you can pass a QGuardedPtr<X> to a function where an X* is retquired.
Cast operator; implements pointer semantics. Because of this function you can pass a QGuardedPtr<X> to a function where an X* is required.
.SH "bool QGuardedPtr::operator!= ( const QGuardedPtr<T> & p ) const"
Inequality operator; implements pointer semantics, the negation of operator==(). Returns TRUE if \fIp\fR and this guarded pointer are not pointing to the same object; otherwise returns FALSE.
@ -342,7 +342,7 @@ See also hasPendingRequests() and abort().
.SH "int QHttp::closeConnection ()"
Closes the connection; this is useful if you have a keep-alive connection and want to close it.
.PP
For the requests issued with get(), post() and head(), QHttp sets the connection to be keep-alive. You can also do this using the header you pass to the request() function. QHttp only closes the connection to the HTTP server if the response header retquires it to do so.
For the requests issued with get(), post() and head(), QHttp sets the connection to be keep-alive. You can also do this using the header you pass to the request() function. QHttp only closes the connection to the HTTP server if the response header requires it to do so.
.PP
The function does not block and returns immediately. The request is scheduled, and its execution is performed asynchronously. The function returns a unique identifier which is passed by requestStarted() and requestFinished().
@ -88,7 +88,7 @@ The QIconSet class provides a set of icons with different styles and sizes.
.PP
A QIconSet can generate smaller, larger, active, and disabled pixmaps from the set of icons it is given. Such pixmaps are used by QToolButton, QHeader, QPopupMenu, etc. to show an icon representing a particular action.
.PP
The simplest use of QIconSet is to create one from a QPixmap and then use it, allowing Qt to work out all the retquired icon styles and sizes. For example:
The simplest use of QIconSet is to create one from a QPixmap and then use it, allowing Qt to work out all the required icon styles and sizes. For example:
.PP
.nf
.br
@ -165,7 +165,7 @@ This enum type describes the size at which a pixmap is intended to be used. The
.TP
\fCQIconSet::Large\fR - The pixmap is the larger of two.
.PP
If a Small pixmap is not set by QIconSet::setPixmap(), the Large pixmap will be automatically scaled down to the size of a small pixmap to generate the Small pixmap when retquired. Similarly, a Small pixmap will be automatically scaled up to generate a Large pixmap. The preferred sizes for large/small generated icons can be set using setIconSize().
If a Small pixmap is not set by QIconSet::setPixmap(), the Large pixmap will be automatically scaled down to the size of a small pixmap to generate the Small pixmap when required. Similarly, a Small pixmap will be automatically scaled up to generate a Large pixmap. The preferred sizes for large/small generated icons can be set using setIconSize().
.PP
See also setIconSize(), iconSize(), setPixmap(), pixmap(), and QMainWindow::usesBigPixmaps.
@ -390,7 +390,7 @@ This enum type is used to describe the endianness of the CPU and graphics hardwa
.TP
\fCQImage::LittleEndian\fR - PC/Alpha byte order.
.SH "QImage::ScaleMode"
The functions scale() and smoothScale() use different modes for scaling the image. The purpose of these modes is to retain the ratio of the image if this is retquired.
The functions scale() and smoothScale() use different modes for scaling the image. The purpose of these modes is to retain the ratio of the image if this is required.
@ -53,9 +53,9 @@ A QImageDecoder is a machine that decodes images. It takes encoded image data vi
.PP
QImageFormatType and QImageFormat are the classes that you might need to implement support for additional image formats.
.PP
Qt supports GIF reading if it is configured that way during installation (see qgif.h). If it is, we are retquired to state that" The Graphics Interchange Format(c) is the Copyright property of CompuServe Incorporated. GIF(sm) is a Service Mark property of CompuServe Incorporated."
Qt supports GIF reading if it is configured that way during installation (see qgif.h). If it is, we are required to state that" The Graphics Interchange Format(c) is the Copyright property of CompuServe Incorporated. GIF(sm) is a Service Mark property of CompuServe Incorporated."
.PP
\fBWarning:\fR If you are in a country that recognizes software patents and in which Unisys holds a patent on LZW compression and/or decompression and you want to use GIF, Unisys may retquire you to license that technology. Such countries include Canada, Japan, the USA, France, Germany, Italy and the UK.
\fBWarning:\fR If you are in a country that recognizes software patents and in which Unisys holds a patent on LZW compression and/or decompression and you want to use GIF, Unisys may require you to license that technology. Such countries include Canada, Japan, the USA, France, Germany, Italy and the UK.
.PP
GIF support may be removed completely in a future version of Qt. We recommend using the MNG or PNG format.
@ -117,7 +117,7 @@ For image files that contain sequences of images, only the first is read. See QM
.PP
PBM, PGM, and PPM format \fIoutput\fR is always in the more condensed raw format. PPM and PGM files with more than 256 levels of intensity are scaled down when reading.
.PP
\fBWarning:\fR If you are in a country which recognizes software patents and in which Unisys holds a patent on LZW compression and/or decompression and you want to use GIF, Unisys may retquire you to license the technology. Such countries include Canada, Japan, the USA, France, Germany, Italy and the UK.
\fBWarning:\fR If you are in a country which recognizes software patents and in which Unisys holds a patent on LZW compression and/or decompression and you want to use GIF, Unisys may require you to license the technology. Such countries include Canada, Japan, the USA, France, Germany, Italy and the UK.
.PP
GIF support may be removed completely in a future version of Qt. We recommend using the PNG format.
Sets the image's parameter string to \fIparameters\fR. This is for image handlers that retquire special parameters.
Sets the image's parameter string to \fIparameters\fR. This is for image handlers that require special parameters.
.PP
Although the current image formats supported by Qt ignore the parameters string, it may be used in future extensions or by contributions (for example, JPEG).
@ -169,7 +169,7 @@ Returns the address of the exported symbol \fIsymb\fR. The library is loaded if
.br
.fi
.PP
The symbol must be exported as a C-function from the library. This retquires the \fCextern "C"\fR notation if the library is compiled with a C++ compiler. On Windows you also have to explicitly export the function from the DLL using the \fC__declspec(dllexport)\fR compiler directive.
The symbol must be exported as a C-function from the library. This requires the \fCextern "C"\fR notation if the library is compiled with a C++ compiler. On Windows you also have to explicitly export the function from the DLL using the \fC__declspec(dllexport)\fR compiler directive.
@ -666,7 +666,7 @@ Unset the mask and return to normal QLineEdit operation by passing an empty stri
.PP
The mask format understands these mask characters: <center>.nf
.TS
l - l. Character Meaning ASCII alphabetic character retquired. A-Z, a-z. ASCII alphabetic character permitted but not retquired. ASCII alphanumeric character retquired. A-Z, a-z, 0-9. ASCII alphanumeric character permitted but not retquired. Any character retquired. x Any character permitted but not retquired. ASCII digit retquired. 0-9. ASCII digit permitted but not retquired. ASCII digit retquired. 1-9. ASCII digit permitted but not retquired (1-9). ASCII digit or plus/minus sign permitted but not retquired. All following alphabetic characters are uppercased. All following alphabetic characters are lowercased. Switch off case conversion. Use
l - l. Character Meaning ASCII alphabetic character required. A-Z, a-z. ASCII alphabetic character permitted but not required. ASCII alphanumeric character required. A-Z, a-z, 0-9. ASCII alphanumeric character permitted but not required. Any character required. x Any character permitted but not required. ASCII digit required. 0-9. ASCII digit permitted but not required. ASCII digit required. 1-9. ASCII digit permitted but not required (1-9). ASCII digit or plus/minus sign permitted but not required. All following alphabetic characters are uppercased. All following alphabetic characters are lowercased. Switch off case conversion. Use
.TE
.fi
</center>
Some files were not shown because too many files have changed in this diff
Show More
