os::Clipboard Class Reference
[Various utillity classes.]

Description:

A clipboard allows a user to save data that is "Cut" or "Copied" from an application.

More...

List of all members.

Public Member Functions
	Clipboard (const String &cName="")
	Constructor.
	~Clipboard ()
	Destructor.
bool	Lock ()
	Locks the clipboard.
void	Unlock ()
	Unlocks the clipboard.
void	Clear ()
	Clears the clipboard.
void	Commit ()
	Adds the data to the clipboard.
Message *	GetData ()
	Returns the data that was added to the clipboard.
Classes
class	Private
	internal More...

---

Detailed Description

A clipboard is very useful with TextViews and the such where users have massive amounts of data that they want to manipulate.

Usage:

A clipboard can be very confusing to use so this little code can help you out a lot.

If you wish to add a clip to the clipboard you can do:

                        Clipboard cClipboard;

                        //we lock the clipboard and then we clear the data's contents
                        cClipboard.Lock();
                        cClipboard.Clear();
                        
                        //we get the clipboard message and then we add a string to it under "text/plain"
                        Message *pcData = cClipboard.GetData();
                        pcData->AddString( "text/plain", *pcBuffer );
                        
                        //we committ our changes and then we unlock the clipboard
                        cClipboard.Commit();
                        cClipboard.Unlock();

If you wish to get the clipboard contents, you can do:

                const char *pzBuffer;
                int nError;
                Clipboard cClipboard;

                //lock the clipboard and get the data from the clipboard
                cClipboard.Lock();
                Message *pcData = cClipboard.GetData();

                //the data that is in the clipboard is plain text, so you find a string in the message that is "text/plain"
                //nError will be 0 there isn't any strings in the message under the name "text/plain"
                //The string "text/plain" will likely change to something a little more generic to allow more than just strings to be clipped. 
                nError = pcData->FindString( "text/plain", &pzBuffer );

                //add some error checking
                if( nError == 0 )
                {
                        //we found the data, so you can do whatever with the data
                }

If you wish to monitor the activity of the clipboard you need to monitor its event:

                m_pcMonitorEvent = new os::Event();
                m_pcMonitorEvent->SetToRemote( "os/System/ClipboardHasChanged", -1 );
                m_pcMonitorEvent->SetMonitorEnabled( true, this ( your handler), MSG_CLIP_CHANGED (the code you will receive a message under) );

See also:

os::TextView, os::Message, os::Event

Author:

Kurt Skauen ([email protected])

Rick Caudill ([email protected])

---

Constructor & Destructor Documentation

Clipboard::Clipboard

(

const String &

cName = ""

)

Description:

os::Clipboard constructor.

Parameters:

cName

- The name of the clipboard. If you pass a null string or just call the contructor the name that will be __system_clipboard__

Author:

Rick Caudill([email protected])

Clipboard::~Clipboard

(

)

Description:

os::Clipboard destructor will delete the reply port, the event, and then get rid of all the private information.

Author:

Rick Caudill([email protected])

---

Member Function Documentation

bool Clipboard::Lock

(

)

Description:

This function will always return true, but before doing so it sets the mutex of this clipboard to lock and then makes note that we haven't cleared the clipboard.

Note:

Before doing anything with the clipboard, you should lock it.

If you Lock something then you must Unlock it.

See also:

Unlock(), os::Locker

Author:

Rick Caudill([email protected])

void Clipboard::Unlock

(

)

Description:

This function unlocks the clipboard, but only after clearing the old clips out of the clipboard.

Note:

Before doing anything with the clipboard, you should Lock it.

If you Lock something then you must Unlock it.

See also:

Lock(), os::Locker

Author:

Rick Caudill([email protected])

void Clipboard::Clear

(

)

Description:

This function doesn't actually clear the clipboard, but it sets a flag so when the programmer calls GetData() the data is cleared.

Note:

You cannot use the Clipboard class outside of an application object, because the event is sent to the current application object.

Before doing anything with the clipboard, you should Lock it.

If you Lock something then you must Unlock it.

See also:

Unlock(), os::Locker

Author:

Rick Caudill([email protected])

void Clipboard::Commit

(

)

Description:

This function will add the data clipboard last. This is just a container for a Clip that is sent to the appserver and then is retrieved via GeData().

Note:

This function sends to the syllable appserver itself(via send_msg).

You cannot use the Clipboard class outside of an application object, because the event is sent to the current application object.

Before doing anything with the clipboard, you should lock it.

If you Lock something then you must Unlock it.

See also:

Unlock(), GetData(), os::Locker

Author:

Rick Caudill([email protected])

Message * Clipboard::GetData

(

)

Description:

This function gets the data that was added to the clipboard last and it then returns it

Note:

This function calls the syllable appserver itself.

You cannot use the Clipboard class outside of an application object, because the event is sent to the current application object.

Before doing anything with the clipboard, you should lock it.

If you Lock something then you must Unlock it.

See also:

Unlock(), Commit(), os::Locker

Author:

Rick Caudill([email protected])

---