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 / khexedit / byteseditinterface.h next >
Encoding:
C/C++ Source or Header  |  2005-09-10  |  8.4 KB  |  230 lines
  1. /***************************************************************************
  2.                           byteseditinterface.h  -  description
  3.                              -------------------
  4.     begin                : Fri Sep 12 2003
  5.     copyright            : (C) 2003 by Friedrich W. H. Kossebau
  6.     email                : Friedrich.W.H@Kossebau.de
  7.  ***************************************************************************/
  8.  
  9. /***************************************************************************
  10.  *                                                                         *
  11.  *   This library is free software; you can redistribute it and/or         *
  12.  *   modify it under the terms of the GNU Library General Public           *
  13.  *   License version 2 as published by the Free Software Foundation.       *
  14.  *                                                                         *
  15.  ***************************************************************************/
  16.  
  17.  
  18. #ifndef BYTESEDITINTERFACE_H
  19. #define BYTESEDITINTERFACE_H
  20.  
  21. // kde specific
  22. #include <kparts/componentfactory.h>
  23.  
  24. #include <qwidget.h>
  25.  
  26. /**
  27.  * @short KHE (short for KHexEdit) is KDE's namespace for all things related
  28.  * to the viewing/editing of bytes.
  29.  *
  30.  * @since 3.2
  31.  */
  32. namespace KHE
  33. {
  34.  
  35. /**
  36.  * @short An interface for a hex edit editor/viewer for arrays of byte
  37.  *
  38.  * \code
  39.  *  KHE::BytesEditInterface *BytesEdit = KHE::bytesEditInterface( BytesEditWidget );
  40.  * \endcode
  41.  *
  42.  * It can be used in different ways:
  43.  * <ul>
  44.  * <li> as an viewer for array char* Data, sized DataSize
  45.  * \code
  46.  * BytesEdit->setData( Data, DataSize );
  47.  * BytesEdit->setReadOnly( true );
  48.  * \endcode
  49.  *
  50.  * <li> as an editor for a given array of bytes with a fixed size
  51.  * \code
  52.  * BytesEdit->setData( Data, DataSize );
  53.  * BytesEdit->setOverWriteOnly( true );
  54.  * \endcode
  55.  *
  56.  * <li> as an editor for a given array of bytes with a limited size
  57.  * \code
  58.  * BytesEdit->setData( Data, DataSize, -1, false );
  59.  * BytesEdit->setMaxDataSize( MaxDataSize );
  60.  * BytesEdit->setOverWriteMode( false );
  61.  * \endcode
  62.  *
  63.  * <li> as an editor for a new to be created array of chars, max. with MaxDataSize
  64.  * \code
  65.  * BytesEdit->setMaxDataSize( MaxDataSize );
  66.  * ...
  67.  * QByteArray BA;
  68.  * BA.setRawData( BytesEdit->data(), BytesEdit->dataSize() );
  69.  * \endcode
  70.  * </ul>
  71.  *
  72.  * @author Friedrich W. H. Kossebau <Friedrich.W.H@Kossebau.de>
  73.  * @see createBytesEditWidget(), bytesEditInterface()
  74.  * @since 3.2
  75.  */
  76. class BytesEditInterface
  77. {
  78.   public:
  79.     //static const char Name[] = "KHE::BytesEditInterface";
  80.  
  81.   public: // set methods
  82.     /** hands over to the editor a new byte array.
  83.       * If there exists an old one and autodelete is set the old one gets deleted.
  84.       * @param D pointer to memory
  85.       * @param S size of used memory
  86.       * @param RS real size of the memory, -1 means S is the real size
  87.       * @param KM keep the memory on resize (RS is the maximum size)
  88.       */
  89.     virtual void setData( char *D, int S, int RS = -1, bool KM = true ) = 0;
  90.     /** sets whether the given array should be handled read only or not. Default is false. */
  91.     virtual void setReadOnly( bool RO = true ) = 0;
  92.     /** sets the maximal size of the actual byte array. If the actual array is already larger
  93.       * it will not be modified but there can be only done non-inserting actions
  94.       * until the array's is below the limit
  95.       * If the flag KeepsMemory is set MaxDataSize is limited to the real size of the array.
  96.       * MaxDataSize == -1 means no limit.
  97.       * Default is -1.
  98.       * @param MS new maximal data size
  99.       */
  100.     virtual void setMaxDataSize( int MS ) = 0;
  101.     /** sets whether the array should be deleted on the widget's end or if a new array is set.
  102.       * Default is false
  103.       */
  104.     virtual void setAutoDelete( bool AD = true ) = 0;
  105.     /** switches the array */
  106. //    virtual void resetData( char *D, int S, bool Repaint ) = 0;
  107.     /** sets whether the actual memory used to store the data
  108.       * (as given by setData or in the constructor, or allocated by the class)
  109.       * should be kept on resize.
  110.       * If MaxDataSize is set and greater than the raw size of the memory
  111.       * it is limited to the raw size.
  112.       * Default is false.
  113.       */
  114.     virtual void setKeepsMemory( bool KM = true ) = 0;
  115.   //
  116.     /** sets whether the widget is overwriteonly or not. Default is false. */
  117.     virtual void setOverwriteOnly( bool b ) = 0;
  118.     /** sets whether the widget is in overwrite mode or not. Default is true. */
  119.     virtual void setOverwriteMode( bool b ) = 0;
  120.     /** sets whether the data should be treated modified or not */
  121.     virtual void setModified( bool b ) = 0;
  122.  
  123.  
  124.   public: // get methods
  125.     /** @return a pointer to the actual byte array */
  126.     virtual char *data() const = 0;
  127.     /** @return the size of the actual byte array */
  128.     virtual int dataSize() const = 0;
  129.     /** @return the maximal allowed size for the byte array */
  130.     virtual int maxDataSize () const = 0;
  131.     /** @return whether autodelete is set for the byte array */
  132.     virtual bool isAutoDelete() const = 0;
  133.     /** @return @c true if the memory of the byte array is kept, otherwise @c false */
  134.     virtual bool keepsMemory() const = 0;
  135.  
  136.     /** @return @c true if the edit mode is overwrite, otherwise @c false for insert mode*/
  137.     virtual bool isOverwriteMode() const = 0;
  138.     /** @return @c true if the memory of the byte array is kept, otherwise @c false */
  139.     virtual bool isOverwriteOnly() const = 0;
  140.     /** @return @c true if the ReadOnly flag is set, otherwise @c false */
  141.     virtual bool isReadOnly() const = 0;
  142.     /** @return @c true if the Modified flag is set, otherwise @c false */
  143.     virtual bool isModified() const = 0;
  144.  
  145.   public: // call for action
  146.     /** repaint the indizes from i1 to i2 */
  147.     virtual void repaintRange( int i1, int i2 ) = 0;
  148. };
  149.  
  150.  
  151. /** tries to get the bytesedit interface of t
  152.   * @return a pointer to the interface, otherwise 0
  153.   * @author Friedrich W. H. Kossebau <Friedrich.W.H@Kossebau.de>
  154.   * @since 3.2
  155. */
  156. template<class T>
  157. inline BytesEditInterface *bytesEditInterface( T *t )
  158. {
  159.   if( !t )
  160.     return 0;
  161.  
  162.   return static_cast<BytesEditInterface*>( t->qt_cast("KHE::BytesEditInterface") );
  163. }
  164.  
  165. /** tries to create an instance of a hexedit widget for arrays of chars (char[])
  166.   *
  167.   * Usage:
  168.   *
  169.   * \code
  170.   * #include <khexedit/byteseditinterface.h>
  171.   * #include <khexedit/valuecolumninterface.h>
  172.   * #include <khexedit/charcolumninterface.h>
  173.   * #include <khexedit/clipboardinterface.h>
  174.   * ...
  175.   *
  176.   * QWidget *BytesEditWidget = KHE::createBytesEditWidget( this, "BytesEditWidget" );
  177.   * // is e.g. kdeutils (incl. khexedit2) installed, so a widget could be found and created?
  178.   * if( BytesEditWidget )
  179.   * {
  180.   * á // fetch the editor interface
  181.   * á KHE::BytesEditInterface *BytesEdit = KHE::bytesEditInterface( BytesEditWidget );
  182.   * á Q_ASSERT( BytesEdit ); // This should not fail!
  183.   *
  184.   * á // now use the editor.
  185.   * á BytesEdit->setData( Buffer, BufferSize, -1 );
  186.   * á BytesEdit->setMaxDataSize( BufferSize );
  187.   * á BytesEdit->setReadOnly( false );
  188.   * á BytesEdit->setAutoDelete( true );
  189.   *
  190.   * á KHE::ValueColumnInterface *ValueColumn = KHE::valueColumnInterface( BytesEditWidget );
  191.   * á if( ValueColumn )
  192.   * á {
  193.   * á á ValueColumn->setCoding( KHE::ValueColumnInterface::BinaryCoding );
  194.   * á á ValueColumn->setByteSpacingWidth( 2 );
  195.   * á á ValueColumn->setNoOfGroupedBytes( 4 );
  196.   * á á ValueColumn->setGroupSpacingWidth( 12 );
  197.   * á }
  198.   *
  199.   * á KHE::CharColumnInterface *CharColumn = KHE::charColumnInterface( BytesEditWidget );
  200.   * á if( CharColumn )
  201.   * á {
  202.   * á á CharColumn->setShowUnprintable( false );
  203.   * á á CharColumn->setSubstituteChar( '*' );
  204.   * á }
  205.   * á KHE::ClipboardInterface *Clipboard = KHE::clipboardInterface( BytesEditWidget );
  206.   * á if( Clipboard )
  207.   * á {
  208.   * á á // Yes, use BytesEditWidget, not Clipboard, because that's the QObject, indeed hacky...
  209.   * á á connect( BytesEditWidget, SIGNAL(copyAvailable(bool)), this, SLOT(offerCopy(bool)) );
  210.   * á }
  211.   * }
  212.   * \endcode
  213.   *
  214.   * @param Parent  parent widget
  215.   * @param Name    identifier
  216.   * @return a pointer to the widget, otherwise 0
  217.   * @author Friedrich W. H. Kossebau <Friedrich.W.H@Kossebau.de>
  218.   * @see BytesEditInterface, ValueColumnInterface, CharColumnInterface, ZoomInterface, ClipboardInterface
  219.   * @since 3.2
  220.   */
  221. inline QWidget *createBytesEditWidget( QWidget *Parent = 0, const char *Name = 0 )
  222. {
  223.   return KParts::ComponentFactory::createInstanceFromQuery<QWidget>
  224.       ( QString::fromLatin1("KHexEdit/KBytesEdit"), QString::null, Parent, Name );
  225. }
  226.  
  227. }
  228.  
  229. #endif
  230.