org.eclipse.swt.widgets.Caret Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of org.eclipse.swt.gtk.linux.ppc64le Show documentation
Standard Widget Toolkit for GTK on ppc64le
The newest version!
/*******************************************************************************
 * Copyright (c) 2000, 2019 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.swt.widgets;


import org.eclipse.swt.*;
import org.eclipse.swt.graphics.*;
import org.eclipse.swt.internal.*;
import org.eclipse.swt.internal.cairo.*;
import org.eclipse.swt.internal.gtk.*;

/**
 * Instances of this class provide an i-beam that is typically used
 * as the insertion point for text.
 * 
 * Styles:
 * (none)
 * Events:
 * (none)
 * 
 * 
 * IMPORTANT: This class is not intended to be subclassed.
 * 
 *
 * @see Caret snippets
 * @see SWT Example: ControlExample, Canvas tab
 * @see Sample code and further information
 * @noextend This class is not intended to be subclassed by clients.
 */
public class Caret extends Widget {
	Canvas parent;
	// Table or Tree the parent might be embedded into (also indirectly)
	Composite embeddedInto;
	int x, y, width, height;
	boolean isVisible, isShowing;
	int blinkRate;
	Image image;
	Font font;

	static final int DEFAULT_WIDTH = 1;

/**
 * Constructs a new instance of this class given its parent
 * and a style value describing its behavior and appearance.
 * 
 * The style value is either one of the style constants defined in
 * class SWT which is applicable to instances of this
 * class, or must be built by bitwise OR'ing together
 * (that is, using the int "|" operator) two or more
 * of those SWT style constants. The class description
 * lists the style constants that are applicable to the class.
 * Style bits are also inherited from superclasses.
 * 
 *
 * @param parent a composite control which will be the parent of the new instance (cannot be null)
 * @param style the style of control to construct
 *
 * @exception IllegalArgumentException 
 *    ERROR_NULL_ARGUMENT - if the parent is null
 * 
 * @exception SWTException 
 *    ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
 *    ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass
 * 
 *
 * @see SWT
 * @see Widget#checkSubclass
 * @see Widget#getStyle
 */
public Caret (Canvas parent, int style) {
	super (parent, style);
	this.parent = parent;
	createWidget (0);
	Composite p = parent.getParent();
	while (p != null) {
		if (p instanceof Tree || p instanceof Table) {
			embeddedInto = p;
			break;
		}
		p = p.getParent();
	}
}

boolean blinkCaret () {
	if (!isVisible) return true;
	if (!isShowing) return showCaret ();
	if (blinkRate == 0) return true;
	return hideCaret ();
}

@Override
void createWidget (int index) {
	super.createWidget (index);
	blinkRate = display.getCaretBlinkTime ();
	isVisible = true;
	if (parent.getCaret () == null) {
		parent.setCaret (this);
	}
}

boolean drawCaret () {
	if (parent == null) return false;
	if (parent.isDisposed ()) return false;
	if (embeddedInto != null && !embeddedInto.isDisposed() && isFocusCaret()) {
		// Draw differently if we are in the embedded cell editor
		// See Table.setParentGdkResource() and Tree.setParentGdkResource()
		drawInCellEditor(embeddedInto.paintWindow());
	} else {
		GTK.gtk_widget_queue_draw(parent.handle);
	}
	return true;
}

private void drawInCellEditor(long window) {
	long cairo = GDK.gdk_cairo_create(window);
	Point pt = display.map(parent, embeddedInto, new Point(0,0));
	Cairo.cairo_translate (cairo, pt.x, pt.y);
	parent.drawCaretInFocus(parent.handle, cairo);
	Cairo.cairo_destroy(cairo);
}

/**
 * Returns a rectangle describing the receiver's size and location
 * relative to its parent (or its display if its parent is null).
 *
 * @return the receiver's bounding rectangle
 *
 * @exception SWTException 
 *    ERROR_WIDGET_DISPOSED - if the receiver has been disposed
 *    ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
 * 
 */
public Rectangle getBounds () {
	checkWidget();
	return DPIUtil.autoScaleDown(getBoundsInPixels());
}

Rectangle getBoundsInPixels () {
	checkWidget();
	if (image != null) {
		Rectangle rect = image.getBoundsInPixels ();
		return new Rectangle (x, y, rect.width, rect.height);
	} else {
		if (width == 0) {
			return new Rectangle (x, y, DEFAULT_WIDTH, height);
		}
	}
	return new Rectangle (x, y, width, height);
}

/**
 * Returns the font that the receiver will use to paint textual information.
 *
 * @return the receiver's font
 *
 * @exception SWTException 
 *    ERROR_WIDGET_DISPOSED - if the receiver has been disposed
 *    ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
 * 
 */
public Font getFont () {
	checkWidget();
	if (font != null) return font;
	return parent.getFont ();
}

/**
 * Returns the image that the receiver will use to paint the caret.
 *
 * @return the receiver's image
 *
 * @exception SWTException 
 *    ERROR_WIDGET_DISPOSED - if the receiver has been disposed
 *    ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
 * 
 */
public Image getImage () {
	checkWidget();
	return image;
}

/**
 * Returns a point describing the receiver's location relative
 * to its parent (or its display if its parent is null).
 *
 * @return the receiver's location
 *
 * @exception SWTException 
 *    ERROR_WIDGET_DISPOSED - if the receiver has been disposed
 *    ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
 * 
 */
public Point getLocation () {
	checkWidget();
	return DPIUtil.autoScaleDown(getLocationInPixels());
}

Point getLocationInPixels () {
	checkWidget();
	return new Point (x, y);
}

/**
 * Returns the receiver's parent, which must be a Canvas.
 *
 * @return the receiver's parent
 *
 * @exception SWTException 
 *    ERROR_WIDGET_DISPOSED - if the receiver has been disposed
 *    ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
 * 
 */
public Canvas getParent () {
	checkWidget();
	return parent;
}

/**
 * Returns a point describing the receiver's size.
 *
 * @return the receiver's size
 *
 * @exception SWTException 
 *    ERROR_WIDGET_DISPOSED - if the receiver has been disposed
 *    ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
 * 
 */
public Point getSize () {
	checkWidget();
	return DPIUtil.autoScaleDown(getSizeInPixels());
}

Point getSizeInPixels () {
	checkWidget();
	if (image != null) {
		Rectangle rect = image.getBoundsInPixels ();
		return new Point (rect.width, rect.height);
	} else {
		if (width == 0) {
			return new Point (DEFAULT_WIDTH, height);
		}
	}
	return new Point (width, height);
}

/**
 * Returns true if the receiver is visible, and
 * false otherwise.
 * 
 * If one of the receiver's ancestors is not visible or some
 * other condition makes the receiver not visible, this method
 * may still indicate that it is considered visible even though
 * it may not actually be showing.
 * 
 *
 * @return the receiver's visibility state
 *
 * @exception SWTException 
 *    ERROR_WIDGET_DISPOSED - if the receiver has been disposed
 *    ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
 * 
 */
public boolean getVisible () {
	checkWidget();
	return isVisible;
}

boolean hideCaret () {
	if (!isShowing) return true;
	isShowing = false;
	return drawCaret ();
}

/**
 * Returns true if the receiver is visible and all
 * of the receiver's ancestors are visible and false
 * otherwise.
 *
 * @return the receiver's visibility state
 *
 * @exception SWTException 
 *    ERROR_WIDGET_DISPOSED - if the receiver has been disposed
 *    ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
 * 
 *
 * @see #getVisible
 */
public boolean isVisible () {
	checkWidget();
	return isVisible && parent.isVisible () && parent.hasFocus ();
}

boolean isFocusCaret () {
	return this == display.currentCaret;
}

void killFocus () {
	if (display.currentCaret != this) return;
	display.setCurrentCaret (null);
	if (isVisible) hideCaret ();
}

@Override
void releaseParent () {
	super.releaseParent ();
	if (parent != null && this == parent.caret) {
		if (!parent.isDisposed()) parent.setCaret (null);
		else parent.caret = null;
	}
}

@Override
void releaseWidget () {
	super.releaseWidget ();
	if (display.currentCaret == this) {
		hideCaret ();
		display.setCurrentCaret (null);
	}
	parent = null;
	image = null;
	embeddedInto = null;
}

/**
 * Sets the receiver's size and location to the rectangular
 * area specified by the arguments. The x and
 * y arguments are relative to the receiver's
 * parent (or its display if its parent is null).
 *
 * @param x the new x coordinate for the receiver
 * @param y the new y coordinate for the receiver
 * @param width the new width for the receiver
 * @param height the new height for the receiver
 *
 * @exception SWTException 
 *    ERROR_WIDGET_DISPOSED - if the receiver has been disposed
 *    ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
 * 
 */
public void setBounds (int x, int y, int width, int height) {
	checkWidget();
	setBounds (new Rectangle (x, y, width, height));
}

void setBoundsInPixels (int x, int y, int width, int height) {
	checkWidget();
	if (this.x == x && this.y == y && this.width == width && this.height == height) return;
	boolean isFocus = isFocusCaret ();
	if (isFocus && isVisible) hideCaret ();
	this.x = x; this.y = y;
	this.width = width; this.height = height;
	parent.updateCaret ();
	if (isFocus && isVisible) showCaret ();
}

/**
 * Sets the receiver's size and location to the rectangular
 * area specified by the argument. The x and
 * y fields of the rectangle are relative to
 * the receiver's parent (or its display if its parent is null).
 *
 * @param rect the new bounds for the receiver
 *
 * @exception SWTException 
 *    ERROR_WIDGET_DISPOSED - if the receiver has been disposed
 *    ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
 * 
 */
public void setBounds (Rectangle rect) {
	checkWidget();
	rect = DPIUtil.autoScaleUp(rect);
	setBoundsInPixels(rect);
}

void setBoundsInPixels (Rectangle rect) {
	checkWidget();
	if (rect == null) error (SWT.ERROR_NULL_ARGUMENT);
	setBoundsInPixels (rect.x, rect.y, rect.width, rect.height);
}

void setFocus () {
	if (display.currentCaret == this) return;
	display.setCurrentCaret (this);
	if (isVisible) showCaret ();
}

/**
 * Sets the font that the receiver will use to paint textual information
 * to the font specified by the argument, or to the default font for that
 * kind of control if the argument is null.
 *
 * @param font the new font (or null)
 *
 * @exception IllegalArgumentException 
 *    ERROR_INVALID_ARGUMENT - if the font has been disposed
 * 
 * @exception SWTException 
 *    ERROR_WIDGET_DISPOSED - if the receiver has been disposed
 *    ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
 * 
 */
public void setFont (Font font) {
	checkWidget();
	if (font != null && font.isDisposed ()) {
		error (SWT.ERROR_INVALID_ARGUMENT);
	}
	this.font = font;
}

/**
 * Sets the image that the receiver will use to paint the caret
 * to the image specified by the argument, or to the default
 * which is a filled rectangle if the argument is null
 *
 * @param image the new image (or null)
 *
 * @exception IllegalArgumentException 
 *    ERROR_INVALID_ARGUMENT - if the image has been disposed
 * 
 * @exception SWTException 
 *    ERROR_WIDGET_DISPOSED - if the receiver has been disposed
 *    ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
 * 
 */
public void setImage (Image image) {
	checkWidget();
	if (image != null && image.isDisposed ()) {
		error (SWT.ERROR_INVALID_ARGUMENT);
	}
	boolean isFocus = isFocusCaret ();
	if (isFocus && isVisible) hideCaret ();
	this.image = image;
	if (isFocus && isVisible) showCaret ();
}

/**
 * Sets the receiver's location to the point specified by
 * the arguments which are relative to the receiver's
 * parent (or its display if its parent is null).
 *
 * @param x the new x coordinate for the receiver
 * @param y the new y coordinate for the receiver
 *
 * @exception SWTException 
 *    ERROR_WIDGET_DISPOSED - if the receiver has been disposed
 *    ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
 * 
 */
public void setLocation (int x, int y) {
	checkWidget();
	setLocation (new Point (x, y));
}

void setLocationInPixels (int x, int y) {
	checkWidget();
	setBoundsInPixels (x, y, width, height);
}

/**
 * Sets the receiver's location to the point specified by
 * the argument which is relative to the receiver's
 * parent (or its display if its parent is null).
 *
 * @param location the new location for the receiver
 *
 * @exception SWTException 
 *    ERROR_WIDGET_DISPOSED - if the receiver has been disposed
 *    ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
 * 
 */
public void setLocation (Point location) {
	checkWidget();
	setLocationInPixels (DPIUtil.autoScaleUp (location));
}

void setLocationInPixels (Point location) {
	checkWidget();
	if (location == null) error (SWT.ERROR_NULL_ARGUMENT);
	setLocationInPixels (location.x, location.y);
}

/**
 * Sets the receiver's size to the point specified by the arguments.
 *
 * @param width the new width for the receiver
 * @param height the new height for the receiver
 *
 * @exception SWTException 
 *    ERROR_WIDGET_DISPOSED - if the receiver has been disposed
 *    ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
 * 
 */
public void setSize (int width, int height) {
	checkWidget();
	setSize (new Point (width,height));
}

void setSizeInPixels (int width, int height) {
	checkWidget();
	setBoundsInPixels (x, y, width, height);
}

/**
 * Sets the receiver's size to the point specified by the argument.
 *
 * @param size the new extent for the receiver
 *
 * @exception IllegalArgumentException 
 *    ERROR_NULL_ARGUMENT - if the point is null
 * 
 * @exception SWTException 
 *    ERROR_WIDGET_DISPOSED - if the receiver has been disposed
 *    ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
 * 
 */
public void setSize (Point size) {
	checkWidget();
	setSizeInPixels(DPIUtil.autoScaleUp (size));
}

void setSizeInPixels (Point size) {
	checkWidget();
	if (size == null) error (SWT.ERROR_NULL_ARGUMENT);
	setSizeInPixels (size.x, size.y);
}

/**
 * Marks the receiver as visible if the argument is true,
 * and marks it invisible otherwise.
 * 
 * If one of the receiver's ancestors is not visible or some
 * other condition makes the receiver not visible, marking
 * it visible may not actually cause it to be displayed.
 * 
 *
 * @param visible the new visibility state
 *
 * @exception SWTException 
 *    ERROR_WIDGET_DISPOSED - if the receiver has been disposed
 *    ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
 * 
 */
public void setVisible (boolean visible) {
	checkWidget();
	Canvas canvas = getParent();
	canvas.blink = true;
	canvas.drawFlag = visible;
	display.resetCaretTiming();
	if (visible == isVisible) return;
	isVisible = visible;
	if (!isFocusCaret ()) return;
	if (isVisible) {
		showCaret ();
	} else {
		hideCaret ();
	}
}

boolean showCaret () {
	if (isShowing) return true;
	isShowing = true;
	return drawCaret ();
}

}