From 9f4b42decd28c541bb970462b33495b57cf5b08c Mon Sep 17 00:00:00 2001 From: dsiders Date: Thu, 21 Sep 2023 01:32:46 +0100 Subject: [PATCH] Docs: LCL/clipbrd. Updates topic content. --- docs/xml/lcl/clipbrd.xml | 969 ++++++++++++++++++++------------------- 1 file changed, 498 insertions(+), 471 deletions(-) diff --git a/docs/xml/lcl/clipbrd.xml b/docs/xml/lcl/clipbrd.xml index 52ba25f1b4..a54553e477 100644 --- a/docs/xml/lcl/clipbrd.xml +++ b/docs/xml/lcl/clipbrd.xml @@ -25,91 +25,112 @@ Library (LCL). - Gets the pre-defined clipboard format used for plain text. - - + +TPredefinedClipboardFormat +TClipboardFormat + - - + +TClipboardFormat value registered for the clipboard format. + - + Gets the pre-defined clipboard format used for bitmap images. - - + +TPredefinedClipboardFormat +TClipboardFormat + - - + +TClipboardFormat value registered for the clipboard format. + - + Gets the pre-defined clipboard format used for the LCL Picture type. - - + +TPredefinedClipboardFormat +TClipboardFormat + - - + +TClipboardFormat value registered for the clipboard format. + - + Gets the pre-defined clipboard format used for the LCL Meta-File Picture type. - - + +TPredefinedClipboardFormat +TClipboardFormat + - - + +TClipboardFormat value registered for the clipboard format. + - + Gets the pre-defined clipboard format used for the LCL Object type. - - + +TPredefinedClipboardFormat +TClipboardFormat + - - + +TClipboardFormat value registered for the clipboard format. + - + Gets the pre-defined clipboard format used for the LCL Component type. - - + +TPredefinedClipboardFormat +TClipboardFormat + - - + +TClipboardFormat value registered for the clipboard format. + Gets the pre-defined clipboard format used for HTML content. - + +TPredefinedClipboardFormat +TClipboardFormat + - + +TClipboardFormat value registered for the clipboard format. + - Record type with the format identifier and data for cached clipboard content. @@ -117,13 +138,11 @@ Record type with the format identifier and data for cached clipboard content. - Clipboard format identifier. - Stream with the content stored for the associated clipboard format. @@ -131,19 +150,18 @@ Stream with the content stored for the associated clipboard format. - + -TClipboard - area for holding information that has been cut or -copied, ready for pasting. +Represents the clipboard on platforms supported for the LCL.

-TClipboard - area for holding information that has been cut or -copied, ready for pasting. +TClipboard is an area used to hold information that has been cut or +copied, and is available for pasting.

-The clipboard object encapsulates the Windows clipboard and the three +The clipboard object encapsulates the Windows clipboard as well as the three standard Gtk selections. For each of the three clipboards/selections there is an object: PrimarySelection, SecondarySelection and TPredefinedClipboardFormat, id="#lcl.lcltype.PredefinedClipboardMimeTypes">PredefinedClipboardMimeTypes

- TClipboardFormat, TClipboardType, @@ -170,228 +187,52 @@ id="#lcl.lcltype.PredefinedClipboardMimeTypes">PredefinedClipboardMimeTypesPredefinedClipboardMimeTypes - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Acquires ownership of the Clipboard and adds a format. @@ -399,32 +240,35 @@ id="#lcl.lcltype.PredefinedClipboardMimeTypes">PredefinedClipboardMimeTypes - True if format added correctly. - - + +Clipboard format identifier (TClipboardFormat) updated in the method. + - - + +TStream instance with the content for the specified clipboard format. + - - + +Untyped, updatable buffer with the content stored for the clipboard format. + - - + +Number of bytes in Buffer stored in the method. + - + Copies properties from the specified persistent object to the clipboard. @@ -443,13 +287,12 @@ class types, the inherited method is called. TPersistent.Assign - Persistent object with the property values copied in the method. - + Copies property values into the specified persistent object. @@ -457,43 +300,72 @@ Persistent object with the property values copied in the method. TPersistent - Persistent object where the properties in the class instance are stored. - + -Clear the clipboard. - - - + +Clears the content in the clipboard. + + +

+No actions are performed in the method if nothing has been stored in the cached +clipboard data. +

+

+If the internal cache has format identifiers and data, each TClipboardData +instance is visited to free the TStream with its content. On completion, the +cache is freed and Nil'd and the number of cached clipboard formats is +reset to 0 (zero). +

+ + + + + + - + -Close down the clipboard. - - +Closes down the clipboard. + +

+Calls the EndUpdate method for the clipboard instance. +

+ - + -Create - Constructor: make a new instance of a clipboard. +Constructor for the class instance. - - - + +

+Create is the overloaded constructor for the class instance. +

+

+There is a parameterless variant that reimplements the method from TPersistent +to use the ctClipboard type. A variant which includes the AClipboardType +argument is available; the argument value is stored in the ClipboardType +property for the class instance. It allows creation of clipboard instances used +on the GTK platform. +

+ + + +TClipboardType + - -AClipboardType - optional argument specifying type of clipboard to -be created. +Specified the type of clipboard to be created (normal, primary, or secondary). - + Destructor for the class instance. @@ -505,189 +377,337 @@ destructor prior to exiting from the method. - + -FindPictureFormatID - search for the first format ID that is a -graphic. +Gets the first format ID that is a graphic format supported in TPicture. - - + +TPicture + - -Returns a Clipboard format. +Returns a Clipboard format which supports graphic content. - + -FindFormatID - find a Format ID that has the specified name. +Gets the clipboard format which used the specified name (MIME type). - - - + +

+Used to implement the HasFormatName method, and when assigning the clipboard +content to a TGraphic instance. +

+ + + +TGraphic + - -Returns a Clipboard format. + +Clipboard format with the specified name (MIME type), or 0 (for the Text +format) when not found. + - - + +Name (MIME type) for the clipboard format to locate in the supported Formats. + - + -GetComponent - reads a component from the clipboard. +Gets a TComponent instance with the specified owner and parent from the +clipboard. - - - + +

+GetComponent is an overloaded method in TClipboard used to read a +TComponent instance that was previously stored to the clipboard. +

+

+GetComponent allocates a temporary TMemoryStream which is used to read the +content stored to a pcfComponent clipboard format (when found). The +OnFindComponentClass argument is called to retrieve the class type needed to +re-create the TComponent instance. The ReadComponentFromBinaryStream routine +(in LResources) is called to create the component in the return value using the +arguments to the method. +

+

+The return value is Nil if there is no component on the clipboard with +the Owner and Parent specified in the arguments to the +method. +

+ + +ReadComponentFromBinaryStream + - - + +TComponent instance created from the clipboard data, or Nil when not +found. + - - + +TComponent instance which owns the component on the clipboard. + - - + +TComponent instance which is the parent for the component on the clipboard. + - + + + + +GetComponentAsText - read the component as text, if supported. + + + -GetFormat - read information on format from the clipboard. +Gets the data for the specified clipboard format from the LCL interface or +cached clipboard data. - - - + +

+GetFormat is a Boolean function used to retrieve +clipboard data for the specified format into the specified stream. It uses +cached clipboard data when available, or calls ClipboardGetData in the LCL +interface to retrieve the data for the ClipboardType. +

+

+The return value is True for the following conditions: +

+
    +
  • +Cached data is available and an assigned OnRequest handler was signalled to get +the data for the specified format identifier. +
    • +
  • +Cached data is available and used to load the content in the Stream argument. +
    • +
  • +ClipboardGetData indicates that data has been returned in Stream from the LCL +interface. +
    • +
+

+GetFormat is used in the implementation of methods like GetComponent, +GetTextBuf, and GetAsHtml. It is also called when reading the value for the +AsText property. +

+ + + + + + + + + + - -True if Format found. + +Returns True if data for the format is available, or False when +not found. + - - + +Format ID for the requested clipboard data. + - - + +TStream instance where the data for the format is stored. + - + -SupportedFormats - fills a stringlist with the names of the -supported MIME types. +Gets the list of supported formats for the clipboard. - - + +

+SupportedFormats is an overloaded method in TClipboard. +One variant accepts a TStrings argument where the MIME types for the supported +clipboard formats is stored. The other variant provides updatable variable +arguments which contain the number of supported formats and a pointer to a list +of the supported TClipboardFormat instances. +

+

+Both versions use cached data when available, or call ClipboardGetFormats +in the LCL interface to retrieve the supported clipboard formats. +

+ - - + +TStrings instance with the MIME types for the supported clipboard formats. + - - + +Returns the number of TClipboardFormat instances in FormatList. + - - + +Pointer to a block of TClipboardFormat instances with the supported clipboard +formats. + - + -GetTextBuf - reads text from the clipboard and returns the number -of characters. +Reads text from the clipboard and returns the content and number of characters. - - + +

+GetTextBuf is method used to retrieve text stored in the clipboard +and store it in the Buffer argument. Buffer cannot be Nil, +and must be large enough to store the number of characters requested in the +BufSize argument. +

+

+No actions are performed in the method if Buffer is unassigned or BufSize is +set to 0. +

+

+GetTextBuf use a temporary TMemoryStream instance to load the content from the +text clipboard format, and to store the content to the specified buffer. Buffer +is terminated with a #0 (NUL) character to indicate the end of the data in the +buffer. +

+

+The return value is set to the number characters read from the buffer, or the +number of characters available for the clipboard format when it differs from +the requested size. It is set to 0 (zero) if no data was available on the +clipboard. +

+

+Use the AsText property to retrieve the clipboard content as a String value. +

+ - -Number of characters in text buffer. + +Number of characters stored in the Buffer argument in the method. + - - + +Pointer to the buffer where the text read from the clipboard is stored. + - - + +Number of characters requested from the clipboard. + - + -HasFormat - look up the list to see if the format is supported. If -a TPicture format is specified, all graphic formats are searched. +Determines whether the specified clipboard format is supported for the +clipboard. - +

+If a format for graphics is specified, all graphic formats supported in +TPicture are searched. +

 - -True if format is supported. + +True if the requested format is supported. + - - + +TClipboardFormat requested in the method. + - + -HasFormatName - checks if data have format with specified -name. - - +Indicates whether a clipboard format exists with the specified name (MIME type). + + +

+Calls FindFormatID to get a TClipBoardFormat using the specified MIME type in +FormatName. Returns True if a clipboard format for the name specified in +FormatName exists in the supported formats for the clipboard. +

+ - -True if named format found. + +True if the named format is found. + - - + +Name for the clipboard format (MIME type) requested3 in the method. + - + -HasPictureFormat - checks whether data are formatted as a picture. +Indicates whether a clipboard format for graphical data is present in the +supported formats. - - -True if formatted as picture. + +Returns True if a clipboard format supported in TPicture is found. + - + Open the clipboard to receive and transmit data. - - + +

+Used along with Close to control reading and writing to / from the LCL +interface. If Open has been called, the clipboard will not read from or write +to the LCL interface. Instead it will collect all changes until Close is called. +It will then try to commit all changes as one block. +

+ - + -Write specified component to the Clipboard. - - + +Writes the specified component to the storage for the Clipboard format. + + +

+Clears any existing data stored in the component clipboard format before +storing the binary content in the Component argument. Calls BeginUpdate and +EndUpdate to perform the operation as a single write. +

+ - -Component stored in the clipboard. + +Component stored in the clipboard. + @@ -704,15 +724,14 @@ in the lresources.pp unit to store Component to a AsText property to store the value in the clipboard.

-SetComponentAsText calls BeginUpdate prior to storing the -component to the clipboard, and EndUpdate when the operation has -been completed. The return value for the method is the value returned from -EndUpdate. +SetComponentAsText calls BeginUpdate prior to storing the component to the +clipboard, and EndUpdate when the operation has been completed. The return +value for the method is the value returned from EndUpdate.

-.WriteComponentAsTextToStream +WriteComponentAsTextToStream TMemoryStream @@ -726,7 +745,6 @@ ownership has not changed. - Sets the clipboard format to the specified identifier and copies the value in @@ -757,49 +775,52 @@ instances are loaded to the clipboard in the Assign method. TClipboardFormat - Format identifier needed for the specified stream. - Stream with the content loaded in the method. - + -SetSupportedFormats - set all supported formats at once. +Sets all supported clipboard formats at once. +

SetSupportedFormats sets all supported formats at once All data will be empty. This procedure is useful if setting the OnRequest event to put the data on the fly.

-

Example: Using the PrimarySelection from synedit.pp.

-procedure TCustomSynEdit.AcquirePrimarySelection; +

+Example: Using the PrimarySelection from synedit.pp. +

+ +procedure TCustomSynEdit.AcquirePrimarySelection; var -FormatList: TClipboardFormat; + FormatList: TClipboardFormat; begin -if (not SelAvail) -or (PrimarySelection.OnRequest=@PrimarySelectionRequest) then exit; -FormatList:=CF_TEXT; -PrimarySelection.SetSupportedFormats(1,@FormatList); -PrimarySelection.OnRequest:=@PrimarySelectionRequest; + if (not SelAvail) + or (PrimarySelection.OnRequest=@PrimarySelectionRequest) then exit; + FormatList:=CF_TEXT; + PrimarySelection.SetSupportedFormats(1,@FormatList); + PrimarySelection.OnRequest:=@PrimarySelectionRequest; end; - - - + +Number of clipboard formats in the FormatList argument. + - - + +Pointer to the list of TClipboardFormat instances stored in the method. + - + Loads the clipboard buffer using the text in the specified PChar value. @@ -813,24 +834,35 @@ is loaded in the TClipboardData instances used for the text clipboard format.

- SetTextBuf - PChar value loaded into the clipboard. - + -AsText - holds the textual data in the clipboard as a -string. - +Text stored in the clipboard. + + +

+AsText is a String property with the textual data stored +on the clipboard. The property value is read from an existing pcfText clipboard +format. The return value is an empty string ('') if a clipboard format is not +found for the MIME text type. +

+

+Changing the value for the property causes an assigned OnRequest handler to be +signalled to perform the update. If OnRequest is not assigned, the Clear method +to be called to clear all formats and the data is stored on the clipboard using +the pcfText clipboard format. +

+ - + Puts a HTML string on the clipboard. @@ -840,10 +872,8 @@ a ClipBoard Header. The procedure can also (optionally) set a provided plaintext representation of HTML on the ClipBoard.

- - The HTML string that shall be put on the ClipBoard. @@ -860,7 +890,7 @@ text content of the ClipBoard cleared.

- + Retrieves the HTML content of the clipboard (if available). @@ -870,54 +900,70 @@ will automatically remove the clipboard header that Windows inserts. The resulting HTML string will be UTF-8 encoded.

- - The HTML content of the clipboard as a string. Empty string if the function fails. - + -ClipboardType - ctPrimarySelection, ctSecondarySelection, -ctClipboard. - - - - - - -FormatCount - the number of formats available. - - - - - - -Formats - the formats being used in the current clipboard. +Contains the clipboard type for the platform. +

-Formats - the formats being used in the current clipboard. +ClipboardType is a TClipboardType property which contains +the clipboard type requested in the Create constructor. Some platforms, like +GTK, support more than one clipboard; e. g. normal, primary selection, or +secondary selection clipboard. +

+ + + + + + +Contains the number of clipboard formats supported for the class instance. + + +

+FormatCount is a read-only Integer property with the +number of TClipboardFormat instances found in the cache or returned from the +LCL interface. Calls ClipboardGetFormats to read the supported formats from the +LCL interface. +

+ + + + + + +Contains the clipboard formats currently in use for the class instance. + + +

+Formats is an indexed read-only TClipBoardFormat property which +returns the formats being used in the current clipboard.

You can read the formats with this property one by one. But this will result in many requests, which can be very slow (especially on terminals).

-Better to use "SupportedFormats". +Better to use the SupportedFormats method.

- - + +Ordinal position for the supported clipboard format requested. + - + OnRequest - event handler for a request for clipboard data. @@ -942,7 +988,7 @@ will be called with FormatID=0 to be notified of the loss. - + PrimarySelection - the first selection if multiple clipboards @@ -957,14 +1003,12 @@ On platforms without multiple clipboards, the PrimarySelection still works in the LCL application, but does not communicate with other applications.

- - Returns a variable of type TClipboard. - + SecondarySelection - the second selection if multiple clipboards @@ -978,14 +1022,12 @@ it is free to use. X supports a dozen more selections, but they are not supported by the LCL.

- - Returns a variable of type TClipboard. - + Clipboard the function called to access the clipboard with an @@ -996,78 +1038,63 @@ optional type specifier. The Clipboard is available on most platforms and normally used by Copy/Paste.

- - Returns a variable of type TClipboard. - ClipboardType - optional argument to specify type of clipboard. - + SetClipboard - sets up and returns a NewClipboard, with an optional type specifier. - - Returns a variable of type TClipboard. - ClipboardType - optional argument to specify type of clipboard. - NewClipboard - the new clipboard to be set up. - + FreeAllClipboards - frees all existing clipboards, releasing their resources. - - + RegisterClipboardFormat add the supplied format name to the register of clipboard formats. - - Returns the registered clipboard format. - The name of the required format as a string. - - -GetComponentAsText - read the component as text, if supported. - - +