summaryrefslogtreecommitdiffstats
path: root/tdeprint/kprintdialogpage.h
blob: 353b689869880ac4426773f16e20c852d636a565 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
/*
 *  This file is part of the KDE libraries
 *  Copyright (c) 2001 Michael Goffioul <tdeprint@swing.be>
 *
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Library General Public
 *  License version 2 as published by the Free Software Foundation.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Library General Public License for more details.
 *
 *  You should have received a copy of the GNU Library General Public License
 *  along with this library; see the file COPYING.LIB.  If not, write to
 *  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 *  Boston, MA 02110-1301, USA.
 **/

#ifndef KPRINTDIALOGPAGE_H
#define KPRINTDIALOGPAGE_H

#include <tqwidget.h>
#include <tqmap.h>

#include <tdelibs_export.h>

class KMPrinter;
class DrMain;

/**
 * This class is intended to be used as base class for customized print dialog page. One of
 * the feature of the TDE print framework is to allow to customize the print dialog to
 * add some application specific print options. This is done by subclassing KPrintDialogPage
 * and reimplementing the 3 virtual functions getOptions, setOptions and
 * isValid(). The print options will be stored in the KPrinter object, and will be
 * accessible via KPrinter::option(). The option name should follow the form
 * "kde-appname-optionname" for internal reasons.
 *
 * \code
 * #include <tdeprint/kprintdialogpage.h>
 *
 * class MyDialogPage : public KPrintDialogPage
 * {
 * public:
 *   MyDialogPage( TQWidget *parent = 0, const char *name = 0 );
 *
 *   //reimplement virtual functions
 *   void getOptions( TQMap<TQString,TQString>& opts, bool incldef = false );
 *   void setOptions( const TQMap<TQString,TQString>& opts );
 *   bool isValid( TQString& msg );
 *
 * private:
 *   TQComboBox *m_fontcombo;
 * };
 *
 * MyDialogPage::MyDialogPage( TQWidget *parent, const char *name )
 * : KPrintDialogPage( parent, name )
 * {
 *   setTitle( i18n( "My Page" ) );
 * }
 *
 * void MyDialogPage::getOptions( TQMap<TQString,TQString>& opts, bool incldef )
 * {
 *   if ( incldef || m_fontcombo->currentText() != mydefaultvalue )
 *     opts[ "kde-myapp-fontname" ] = m_fontcombo->currentText();
 * }
 *
 * void MyDialogPage::setOptions( const TQMap<TQString,TQString>& opts )
 * {
 *   TQString fntname = opts[ "kde-myapp-fontname" ];
 *   m_fontcombo->setEditText( fntname );
 * }
 *
 * bool MyDialogPage::isValid( TQString& msg)
 * {
 *   if ( m_fontcombo->currentText().isEmpty() )
 *   {
 *     msg = i18n( "Font name cannot be empty." );
 *     return false;
 *   }
 *   return true;
 * }
 * \endcode
 *
 * @short Base class for customized print dialog pages.
 * @see KPrinter
 */
class TDEPRINT_EXPORT KPrintDialogPage : public TQWidget
{
	TQ_OBJECT
public:
	/**
	 * Standard constructor.
	 */
	KPrintDialogPage(TQWidget *parent = 0, const char *name = 0);
	/**
	 * Modified constructor. For internal use only.
	 */
	KPrintDialogPage(KMPrinter *pr, DrMain *dr = 0, TQWidget *parent = 0, const char *name = 0);
	/**
	 * Destructor
	 */
	virtual ~KPrintDialogPage();

	/**
	 * This function is called to fill the structure @p opts with the selected options from this dialog
	 * page. If @p incldef is true, include also options with default values, otherwise discard them.
	 * Reimplement this function in subclasses.
	 * @param opts the option set to fill
	 * @param incldef if true, include also options with default values
	 * @see setOptions()
	 */
	virtual void getOptions(TQMap<TQString,TQString>& opts, bool incldef = false);
	/**
	 * This function is called to update the current page with the options contained in @p opts.
	 * Reimplement it in subclasses.
	 * @param opts the structure containing the options to update the page
	 */
	virtual void setOptions(const TQMap<TQString,TQString>& opts);
	/**
	 * Returns true if options selected in the page are valid (no conflict), false otherwise.
	 * When returning false, @p msg should contain an error message explaining what is wrong
	 * in the selected options.
	 * @param msg should contain an error message when returning false
	 * @returns valid status
	 */
	virtual bool isValid(TQString& msg);
	/**
	 * Get the ID of the page. Not used yet.
	 * @returns the page ID
	 * @see setId()
	 */
	int id() const 				{ return m_ID; }
	/**
	 * Set the ID of the page. Not used yet.
	 * @param ID the ID number
	 * @see id()
	 */
	void setId(int ID)			{ m_ID = ID; }
	/**
	 * Get the page title.
	 * @returns the page title
	 * @see setTitle()
	 */
	QString	title() const 			{ return m_title; }
	/**
	 * Set the page title. This title will be used as tab name for this page in the print
	 * dialog.
	 * @param txt the page title
	 * @see title()
	 */
	void setTitle(const TQString& txt)	{ m_title = txt; }
	/**
	 * Tell wether or not the page should be disable if a non real printer (special
	 * printer) is selected in the print dialog. Returns false by default. Application
	 * specific pages usually corresponds to printer-independent options, so the
	 * page should be kept enabled whatever the selected printer. The default value
	 * is then correct and your application doesn't to change anything.
	 * @returns true if the page should be disabled for non real printers
	 * @see setOnlyRealPrinters()
	 */
	bool onlyRealPrinters() const	{ return m_onlyreal; }
	/**
	 * Change the page state when a non real printer is selected in the print dialog.
	 * Usually, the default value (false) is OK in most cases and you don't need to
	 * call this function explicitly.
	 * @param on if true, then the page will be disabled if a non real printer is selected
	 * @see onlyRealPrinters()
	 */
	void setOnlyRealPrinters(bool on = true) { m_onlyreal = on; }
	/**
	 * For internal use only.
	 */
	DrMain* driver() 			{ return m_driver; }
	/**
	 * For internal use only
	 */
	KMPrinter* printer()			{ return m_printer; }

protected:
	KMPrinter	*m_printer;
	DrMain		*m_driver;
	int 		m_ID;
	QString		m_title;
	bool		m_onlyreal;
};

#endif