Merge branch 'master' into NSMovie_branch

Author: gcasa

Headers/AppKit/NSButtonCell.h

@@ -62,6 +62,29 @@
 extern "C" {
 #endif
 
+/**
+ * NSButtonTouchBarItem provides a touch-optimized button control specifically
+ * designed for Touch Bar interfaces. It extends the basic NSTouchBarItem
+ * functionality to provide button-specific features such as titles, images,
+ * colors, and action handling optimized for touch interaction.
+ *
+ * This Touch Bar item supports text labels with automatic font optimization
+ * for Touch Bar display, icon and image display with appropriate sizing and
+ * rendering, background colors and visual styling for touch interfaces,
+ * target-action pattern for handling touch events, enabled/disabled state
+ * management, and integration with accessibility services.
+ *
+ * The button automatically adapts its appearance for the Touch Bar environment
+ * with optimized sizing and spacing for finger-based interaction, high-contrast
+ * rendering for the Touch Bar display characteristics, dynamic type support for
+ * accessibility and user preferences, and visual feedback for touch interactions
+ * and state changes.
+ *
+ * NSButtonTouchBarItem is commonly used for primary actions and commands relevant
+ * to the current context, quick access to frequently used application functions,
+ * modal confirmations and secondary action options, and navigation and workflow
+ * control within Touch Bar interfaces.
+ */
 APPKIT_EXPORT_CLASS
 @interface NSButtonTouchBarItem : NSTouchBarItem
 

Headers/AppKit/NSButtonTouchBarItem.h

@@ -1,4 +1,4 @@
-/* 
+/*
    NSCachedImageRep.h
 
    Cached image representation.
@@ -7,7 +7,7 @@
 
    Written by:  Adam Fedor <fedor@colorado.edu>
    Date: Feb 1996
-   
+
    This file is part of the GNUstep GUI Library.
 
    This library is free software; you can redistribute it and/or
@@ -22,10 +22,10 @@
 
    You should have received a copy of the GNU Lesser General Public
    License along with this library; see the file COPYING.LIB.
-   If not, see <http://www.gnu.org/licenses/> or write to the 
-   Free Software Foundation, 51 Franklin Street, Fifth Floor, 
+   If not, see <http://www.gnu.org/licenses/> or write to the
+   Free Software Foundation, 51 Franklin Street, Fifth Floor,
    Boston, MA 02110-1301, USA.
-*/ 
+*/
 
 #ifndef _GNUstep_H_NSCachedImageRep
 #define _GNUstep_H_NSCachedImageRep
@@ -36,6 +36,25 @@
 
 @class NSWindow;
 
+/**
+ * NSCachedImageRep is a specialized image representation that stores
+ * cached bitmap data for efficient drawing operations. It provides a
+ * way to capture and cache the visual content of windows or specific
+ * rectangular areas as bitmap images, enabling fast redrawing and
+ * composition operations without regenerating complex graphics content.
+ *
+ * This class is particularly useful for performance optimization in
+ * scenarios where the same graphical content needs to be drawn repeatedly,
+ * such as during window dragging, animation sequences, or when implementing
+ * custom drawing caches. The cached representation can be created from
+ * existing window content or initialized as an empty bitmap with specific
+ * characteristics.
+ *
+ * NSCachedImageRep supports various pixel formats and color depths,
+ * allowing for optimization based on the specific requirements of the
+ * cached content. It can handle both separate and planar pixel formats,
+ * with optional alpha channel support for transparency effects.
+ */
 APPKIT_EXPORT_CLASS
 @interface NSCachedImageRep : NSImageRep
 {
@@ -45,11 +64,20 @@ APPKIT_EXPORT_CLASS
 }
 
 //
-// Initializing an NSCachedImageRep 
+// Initializing an NSCachedImageRep
 //
 
 /**
  * GNUstep extension
+ *
+ * Initializes a new cached image representation with the specified
+ * dimensions and pixel characteristics. This extended initializer
+ * provides additional control over the pixel format by allowing
+ * specification of both logical size and actual pixel dimensions,
+ * enabling support for high-resolution displays and custom pixel
+ * densities. The depth parameter controls color depth and pixel
+ * format, while separate and alpha flags determine memory layout
+ * and transparency support respectively.
  */
 - (id) initWithSize: (NSSize)aSize
 	 pixelsWide: (NSInteger)pixelsWide
@@ -58,17 +86,48 @@ APPKIT_EXPORT_CLASS
 	   separate: (BOOL)separate
 	      alpha: (BOOL)alpha;
 
+/**
+ * Initializes a new cached image representation with the specified
+ * size and pixel characteristics. This creates an empty bitmap cache
+ * with the given logical size and pixel format properties. The depth
+ * parameter determines the color depth and pixel format, while the
+ * separate flag controls whether pixels are stored in separate planes
+ * or interleaved format. The alpha flag enables transparency support
+ * by including an alpha channel in the pixel format.
+ */
 - (id)initWithSize:(NSSize)aSize
 	     depth:(NSWindowDepth)aDepth
 	  separate:(BOOL)separate
 	     alpha:(BOOL)alpha;
+/**
+ * Initializes a cached image representation by capturing the contents
+ * of a specific rectangular area within the given window. This method
+ * creates a bitmap cache by copying the current visual content of the
+ * specified rectangle from the window's backing store. The cached
+ * representation can then be used for efficient redrawing operations
+ * without requiring regeneration of the original content.
+ */
 - (id)initWithWindow:(NSWindow *)aWindow
 		rect:(NSRect)aRect;
 
 //
-// Getting the Representation 
+// Getting the Representation
 //
+/**
+ * Returns the rectangular area that was cached from the original window.
+ * This rectangle represents the bounds of the content that was captured
+ * when the cached image representation was created using the window-based
+ * initializer. The rectangle is specified in the coordinate system of
+ * the original window from which the content was cached.
+ */
 - (NSRect)rect;
+/**
+ * Returns the window from which this cached image representation was
+ * created. This provides access to the original source window that
+ * was used to capture the cached content. Returns nil if the cached
+ * image representation was created using size-based initialization
+ * rather than window content capture.
+ */
 - (NSWindow *)window;
 
 @end