/*
This file is part of the KDE project

Copyright 2007 by Friedrich W. H. Kossebau <kossebau@kde.org>

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
*/

/** @mainpage KHexEdit


@section khe_intro Introduction

The KHexEdit interfaces - also called KHE interfaces - are a set of
well-defined interfaces which a library can implement to provide
byte level editing services.  Programs which utilise these interfaces
can thus allow the user to choose which implementation of the hex editor component
to use. At the time of KDE 4.2 the only implementation known is the
<a href="http://utils.kde.org/projects/okteta">Okteta</a> Component
(found in
<a href="http://websvn.kde.org/trunk/KDE/kdeutils/okteta/parts/kbytesedit/">kdeutils/okteta/parts/kbytesedit</a>).


@section khe_howto How to use the KHexEdit Interfaces

This HOWTO will explain step by step how to create a KHexEdit component and
prepare it for usage.

@subsection khe_howto_source The code lines

The following source code tries to create a hexedit component.
If the component could not be created, a simple message label is created.
Otherwise we set the data and configure it to our needs
by using the different interfaces if available.


@code
  // used interfaces
  #include <khexedit/byteseditinterface.h>
  #include <khexedit/valuecolumninterface.h>
  #include <khexedit/charcolumninterface.h>
  #include <khexedit/clipboardinterface.h>

  //
  const char *data = 0;
  int dataSize = 0;

  // create data field and set dataSize
  // ...

  QWidget *bytesEditWidget = KHE::createBytesEditWidget( parent );

  // no hexedit component installed?
  if( !bytesEditWidget )
  {
    bytesEditWidget = new QLabel( parent, i18n("Could not find a hexedit component.") );
  }
  // component found and widget created
  else
  {
    // fetch the editor interface
    KHE::BytesEditInterface *bytesEdit = KHE::bytesEditInterface( bytesEditWidget );
    Q_ASSERT( bytesEdit ); // This should not fail!

    // now use the editor.
    bytesEdit->setData( data, dataSize, -1 );
    bytesEdit->setMaxDataSize( dataSize );
    bytesEdit->setReadOnly( false );
    bytesEdit->setAutoDelete( true );

    KHE::ValueColumnInterface *valueColumn = KHE::valueColumnInterface( bytesEditWidget );
    if( valueColumn )
    {
      valueColumn->setCoding( KHE::ValueColumnInterface::BinaryCoding );
      valueColumn->setByteSpacingWidth( 2 );
      valueColumn->setNoOfGroupedBytes( 4 );
      valueColumn->setGroupSpacingWidth( 12 );
    }

    KHE::CharColumnInterface *charColumn = KHE::charColumnInterface( bytesEditWidget );
    if( charColumn )
    {
      charColumn->setShowUnprintable( false );
      charColumn->setSubstituteChar( '*' );
    }

    KHE::ClipboardInterface *clipboard = KHE::clipboardInterface( bytesEditWidget );
    if( clipboard )
    {
      // Yes, use bytesEditWidget, not clipboard, because that's the QObject, indeed hacky...
      connect( bytesEditWidget, SIGNAL(copyAvailable(bool)), this, SLOT(offerCopy(bool)) );
    }
  }

  // now you can use bytesEditWidget like any other widget object...
@endcode

@subsection khe_howto_notes Notes
As the KHexEdit interfaces are header-only, you don't need to link
against any additional libraries.

@authors
Friedrich W. H. Kossebau \<kossebau\@kde.org\>

@maintainers
Friedrich W. H. Kossebau \<kossebau\@kde.org\>

@licenses
@lgpl

*/

// DOXYGEN_REFERENCES = kdecore kdeui kio kparts
// DOXYGEN_SET_PROJECT_NAME = KHexEdit
// vim:ts=4:sw=4:expandtab:filetype=doxygen
