os::Clipboard Class Reference

Classes
class	Private
	internal More...

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

Detailed Description

Description:

A clipboard allows a user to save data that is "Cut" or "Copied" from an application. 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( "pyro/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 (kurt@.nosp@m.athe.nosp@m.os.cx)

Rick Caudill (rick@.nosp@m.syll.nosp@m.able..nosp@m.org)

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(rick@.nosp@m.syll.nosp@m.able..nosp@m.org)

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(rick@.nosp@m.syll.nosp@m.able..nosp@m.org)

References os::Clipboard::Private::m_hReplyPort.

Member Function Documentation

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(rick@.nosp@m.syll.nosp@m.able..nosp@m.org)

References os::Clipboard::Private::m_bCleared.

Referenced by os::TextEdit::GetRegion().

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(rick@.nosp@m.syll.nosp@m.able..nosp@m.org)

References os::String::c_str(), os::Message::Flatten(), os::Message::GetFlattenedSize(), os::Clipboard::Private::m_cBuffer, os::Clipboard::Private::m_cName, os::Clipboard::Private::m_hReplyPort, and os::Clipboard::Private::m_hServerPort.

Referenced by os::TextEdit::GetRegion().

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(rick@.nosp@m.syll.nosp@m.able..nosp@m.org)

References os::String::c_str(), os::Clipboard::Private::m_bCleared, os::Clipboard::Private::m_cBuffer, os::Clipboard::Private::m_cName, os::Clipboard::Private::m_hReplyPort, os::Clipboard::Private::m_hServerPort, os::Message::MakeEmpty(), and os::Message::Unflatten().

Referenced by os::TextEdit::GetRegion(), os::TextEdit::HandleKeyDown(), and os::TextView::Paste().

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(rick@.nosp@m.syll.nosp@m.able..nosp@m.org)

References os::Locker::Lock(), os::Clipboard::Private::m_bCleared, and os::Clipboard::Private::m_cMutex.

Referenced by os::TextEdit::GetRegion(), os::TextEdit::HandleKeyDown(), and os::TextView::Paste().

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(rick@.nosp@m.syll.nosp@m.able..nosp@m.org)

References os::Clipboard::Private::m_cBuffer, os::Clipboard::Private::m_cMutex, os::Message::MakeEmpty(), and os::Locker::Unlock().

Referenced by os::TextEdit::GetRegion(), os::TextEdit::HandleKeyDown(), and os::TextView::Paste().