home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kscan.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-01-15  |  11.1 KB  |  371 lines
  1. /* This file is part of the KDE libraries
  2.     Copyright (C) 2001 Carsten Pfeiffer <pfeiffer@kde.org>
  3.  
  4.     This library is free software; you can redistribute it and/or
  5.     modify it under the terms of the GNU Library General Public
  6.     License as published by the Free Software Foundation; either
  7.     version 2 of the License, or (at your option) any later version.
  8.  
  9.     This library is distributed in the hope that it will be useful,
  10.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12.     Library General Public License for more details.
  13.  
  14.     You should have received a copy of the GNU Library General Public License
  15.     along with this library; see the file COPYING.LIB.  If not, write to
  16.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17.     Boston, MA 02110-1301, USA.
  18. */
  19.  
  20. #ifndef KSCAN_H
  21. #define KSCAN_H
  22.  
  23. #include <kdialogbase.h>
  24. #include <kinstance.h>
  25. #include <klibloader.h>
  26.  
  27. class QImage;
  28.  
  29. /**
  30.  * This is a base class for scanning dialogs. You can derive from this class
  31.  * and implement your own dialog. An implementation is available in
  32.  * kdegraphics/libkscan.
  33.  *
  34.  * Application developers that wish to add scanning support to their program
  35.  * can use the static method @p KScanDialog::getScanDialog() to get an instance
  36.  * of the user's preferred scanning dialog.
  37.  *
  38.  * Typical usage looks like this (e.g. in a slotShowScanDialog() method):
  39.  *
  40.  * \code
  41.  * if ( !m_scanDialog ) {
  42.  *     m_scanDialog = KScanDialog::getScanDialog( this, "scandialog" );
  43.  *     if ( !m_scanDialog ) // no scanning support installed?
  44.  *         return;
  45.  *
  46.  *     connect( m_scanDialog, SIGNAL( finalImage( const QImage&, int )),
  47.  *              SLOT( slotScanned( const QImage&, int ) ));
  48.  * }
  49.  *
  50.  * if ( m_scanDialog->setup() ) // only if scanner configured/available
  51.  *     m_scanDialog->show();
  52.  * \endcode
  53.  *
  54.  * This will create and show a non-modal scanning dialog. Connect to more
  55.  * signals if you like.
  56.  *
  57.  * If you implement an own scan-dialog, you also have to implement a
  58.  * KScanDialogFactory.
  59.  *
  60.  * @short A baseclass and accessor for Scanning Dialogs
  61.  * @author Carsten Pfeiffer <pfeiffer@kde.org>
  62.  */
  63. class KIO_EXPORT KScanDialog : public KDialogBase
  64. {
  65.     Q_OBJECT
  66.  
  67. public:
  68.     /**
  69.      * Creates the user's preferred scanning dialog and returns it,
  70.      * or 0L if no scan-support
  71.      * is available. Pass a suitable @p parent widget, if you like. If you
  72.      * don't you have to 'delete' the returned pointer yourself.
  73.      * @param parent the QWidget's parent, or 0
  74.      * @param name the name of the QObject, can be 0
  75.      * @param modal if true the dialog is model
  76.      * @return the KScanDialog, or 0 if the function failed
  77.      */
  78.     static KScanDialog * getScanDialog( QWidget *parent=0L,
  79.                     const char *name=0, bool modal=false );
  80.     /**
  81.      * Destructs the scan dialog.
  82.      */
  83.     ~KScanDialog();
  84.  
  85.     /**
  86.      * Reimplement this if you need to set up some things, before showing the
  87.      * dialog, e.g. to ask the user for the scanner device to use. If you
  88.      * return false (e.g. there is no device available or the user aborted
  89.      * device selection), the dialog will not be shown.
  90.      *
  91.      * @return true by default.
  92.      */
  93.     virtual bool setup();
  94.  
  95. protected:
  96.     /**
  97.      * Constructs the scan dialog. If you implement an own dialog, you can
  98.      * customize it with the usual KDialogBase flags.
  99.      *
  100.      * @param dialogFace the KDialogBase::DialogType
  101.      * @param buttonMask a ORed mask of all buttons (see
  102.      * KDialogBase::ButtonCode)
  103.      * @param parent the QWidget's parent, or 0
  104.      * @param name the name of the QObject, can be 0
  105.      * @param modal if true the dialog is model
  106.      * @see KDialogBase
  107.      */
  108.     KScanDialog( int dialogFace=Tabbed, int buttonMask = Close|Help,
  109.          QWidget *parent=0L, const char *name=0, bool modal=false );
  110.  
  111.     /**
  112.      * Returns the current id for an image. You can use that in your subclass
  113.      * for the signals. The id is used in the signals to let people know
  114.      * which preview and which text-recognition belongs to which scan.
  115.      *
  116.      * @return the current id for the image
  117.      * @see nextId
  118.      * @see finalImage
  119.      * @see preview
  120.      * @see textRecognized
  121.      */
  122.     int id() const { return m_currentId; }
  123.  
  124.     /**
  125.      * Returns the id for the next image. You can use that in your subclass
  126.      * for the signals.
  127.      *
  128.      * @return the id for the next image
  129.      * @see id
  130.      * @see finalImage
  131.      * @see preview
  132.      * @see textRecognized
  133.      *
  134.      */
  135.     int nextId() { return ++m_currentId; }
  136.  
  137. signals:
  138.     /**
  139.      * Informs you that an image has been previewed.
  140.      * @param img the image
  141.      * @param id the image's id
  142.      */
  143.     void preview( const QImage &img, int id );
  144.  
  145.     /**
  146.      * Informs you that an image has scanned. @p id is the same as in the
  147.      * @p preview() signal, if this image had been previewed before.
  148.      *
  149.      * Note, that those id's may not be properly implemented in the current
  150.      * libkscan.
  151.      * @param img the image
  152.      * @param id the image's id
  153.      */
  154.     void finalImage( const QImage &img, int id );
  155.  
  156.     /**
  157.      * Informs you that the image with the id @p id has been run through
  158.      * text-recognition. The text is in the QString parameter. In the future,
  159.      * a compound document, using rich text will be used instead.
  160.      *
  161.      * @param text the text that has been recognized
  162.      * @param id the id of the image
  163.      */
  164.     void textRecognized( const QString &text, int id );
  165.  
  166. private:
  167.     int m_currentId;
  168.  
  169. protected:
  170.     virtual void virtual_hook( int id, void* data );
  171. private:
  172.     class KScanDialogPrivate;
  173.     KScanDialogPrivate *d;
  174. };
  175.  
  176.  
  177. /**
  178.  * A factory for creating a KScanDialog. You need to reimplement
  179.  * createDialog().
  180.  * @short Factory for creating KScanDialogs
  181.  */
  182. class KIO_EXPORT KScanDialogFactory : public KLibFactory
  183. {
  184. public:
  185.     virtual ~KScanDialogFactory();
  186.  
  187.     /**
  188.      * Your library should reimplement this method to return your KScanDialog
  189.      * derived dialog.
  190.      * @param parent the QWidget's parent, or 0
  191.      * @param name the name of the QObject, can be 0
  192.      * @param modal if true the dialog is model
  193.      */
  194.     virtual KScanDialog * createDialog( QWidget *parent=0, const char *name=0,
  195.                     bool modal=false ) = 0;
  196.  
  197. protected:
  198.     /**
  199.      * Creates a new KScanDialogFactory.
  200.      * @param parent the QWidget's parent, or 0
  201.      * @param name the name of the QObject, can be 0
  202.      */
  203.     KScanDialogFactory( QObject *parent=0, const char *name=0 );
  204.  
  205.     virtual QObject* createObject( QObject* parent = 0, const char* name = 0,
  206.                                    const char* classname = "QObject",
  207.                                    const QStringList &args = QStringList() );
  208.  
  209.  
  210.     /**
  211.      * Creates a new instance with the given name.
  212.      * @param instanceName the name of the instance
  213.      */
  214.     void setName( const QCString& instanceName ) {
  215.     delete m_instance;
  216.     m_instance = new KInstance( instanceName );
  217.     }
  218.  
  219.     /**
  220.      * Returns the instance.
  221.      * @return the KInstance
  222.      */
  223.     KInstance *instance() const { return m_instance; }
  224.  
  225. private:
  226.     KInstance *m_instance;
  227. protected:
  228.     virtual void virtual_hook( int id, void* data );
  229. private:
  230.     class KScanDialogFactoryPrivate* d;
  231. };
  232.  
  233. /**
  234.  * Base class for OCR Dialogs.
  235.  */
  236. class KIO_EXPORT KOCRDialog : public KDialogBase
  237. {
  238.     Q_OBJECT
  239.  
  240. public:
  241.     /**
  242.      * Creates the user's preferred OCR dialog and returns it,
  243.      * or 0L if no OCR-support
  244.      * is available. Pass a suitable @p parent widget, if you like. If you
  245.      * don't you have to 'delete' the returned pointer yourself.
  246.      * @param parent the QWidget's parent, or 0
  247.      * @param name the name of the QObject, can be 0
  248.      * @param modal if true the dialog is model
  249.      * @return the KOCRDialog, or 0 if the function failed
  250.      */
  251.     static KOCRDialog * getOCRDialog( QWidget *parent=0L,
  252.                     const char *name=0, bool modal=false );
  253.     ~KOCRDialog();
  254.  
  255. protected:
  256.     /**
  257.      * Constructs the OCR dialog. If you implement an own dialog, you can
  258.      * customize it with the usual KDialogBase flags.
  259.      *
  260.      * @param dialogFace the KDialogBase::DialogType
  261.      * @param buttonMask a ORed mask of all buttons (see
  262.      * KDialogBase::ButtonCode)
  263.      * @param parent the QWidget's parent, or 0
  264.      * @param name the name of the QObject, can be 0
  265.      * @param modal if true the dialog is model
  266.      */
  267.     KOCRDialog( int dialogFace=Tabbed, int buttonMask = Close|Help,
  268.          QWidget *parent=0L, const char *name=0, bool modal=false );
  269.  
  270.     /**
  271.      * Returns the current id for an image. You can use that in your subclass
  272.      * for the signals. The id is used in the signals to let people know
  273.      * which text-recognition belongs to which scan.
  274.      *
  275.      * @return the current id for the image
  276.      * @see nextId
  277.      * @see textRecognized
  278.      */
  279.     int id() const { return m_currentId; }
  280.  
  281.     /**
  282.      * Returns the id for the next image. You can use that in your subclass
  283.      * for the signals.
  284.      *
  285.      * @return the id for the next image
  286.      * @see id
  287.      * @see textRecognized
  288.      */
  289.     int nextId() { return ++m_currentId; }
  290.  
  291. signals:
  292.     /**
  293.      * Informs you that the image with the id @p id has been run through
  294.      * text-recognition. The text is in the QString parameter. In the future,
  295.      * a compound document, using rich text will be used instead.
  296.      *
  297.      * @param text the text that has been recognized
  298.      * @param id the id of the image
  299.      */
  300.     void textRecognized( const QString &text, int id );
  301.  
  302. private:
  303.     int m_currentId;
  304.  
  305. protected:
  306.     virtual void virtual_hook( int id, void* data );
  307. private:
  308.     class KOCRDialogPrivate;
  309.     KOCRDialogPrivate *d;
  310. };
  311.  
  312.  
  313. /**
  314.  * A factory for creating a KOCRDialog. You need to reimplement
  315.  * createDialog().
  316.  * @short Factory for creating KScanDialogs
  317.  */
  318. class KIO_EXPORT KOCRDialogFactory : public KLibFactory
  319. {
  320. public:
  321.     virtual ~KOCRDialogFactory();
  322.  
  323.     /**
  324.      * Your library should reimplement this method to return your KOCRDialog
  325.      * derived dialog.
  326.      * @param parent the QWidget's parent, or 0
  327.      * @param name the name of the QObject, can be 0
  328.      * @param modal if true the dialog is model
  329.      */
  330.     virtual KOCRDialog * createDialog( QWidget *parent=0, const char *name=0,
  331.                     bool modal=false ) = 0;
  332.  
  333. protected:
  334.     /**
  335.      * Creates a new KScanDialogFactory.
  336.      * @param parent the QWidget's parent, or 0
  337.      * @param name the name of the QObject, can be 0
  338.      */
  339.     KOCRDialogFactory( QObject *parent=0, const char *name=0 );
  340.  
  341.     virtual QObject* createObject( QObject* parent = 0, const char* name = 0,
  342.                                    const char* className = "QObject",
  343.                                    const QStringList &args = QStringList() );
  344.  
  345.  
  346.     /**
  347.      * Creates a new instance with the given name.
  348.      * @param instanceName the name of the instance
  349.      */
  350.     void setName( const QCString& instanceName ) {
  351.     delete m_instance;
  352.     m_instance = new KInstance( instanceName );
  353.     }
  354.  
  355.     /**
  356.      * Returns the instance.
  357.      * @return the KInstance
  358.      */
  359.     KInstance *instance() const { return m_instance; }
  360.  
  361. private:
  362.     KInstance *m_instance;
  363. protected:
  364.     virtual void virtual_hook( int id, void* data );
  365. private:
  366.     class KOCRDialogFactory* d;
  367. };
  368.  
  369.  
  370. #endif // KSCAN_H
  371.