HexFiend
Protected Attributes | Properties | List of all members
HFController Class Reference

A central class that acts as the controller layer for HexFiend.framework. More...

Inheritance diagram for HFController:

Instance Methods

Property transactions

Methods for temporarily delaying notifying representers of property changes. There is a property transaction stack, and all property changes are collected until the last token is popped off the stack, at which point all representers are notified of all collected changes via representerChangedProperties:. To use this, call beginPropertyChangeTransaction, and record the token that is returned. Pass it to endPropertyChangeTransaction: to notify representers of all changed properties in bulk.

Tokens cannot be popped out of order - they are used only as a correctness check.

(NSUInteger) - beginPropertyChangeTransaction
 
(void) - endPropertyChangeTransaction:
 
Properties shared between all representers

The following properties are considered global among all HFRepresenters attached to the receiver.

(unsigned long long) - totalLineCount
 
(NSUInteger) - bytesPerLine
 
(CGFloat) - lineHeight
 
Selection pulsing

Used to show the current selection after a change, similar to Find in Safari

(void) - pulseSelection
 
(double) - selectionPulseAmount
 
(void) - representer:changedProperties:
 
Mouse selection

Methods to handle mouse selection. Representers that allow text selection should call beginSelectionWithEvent:forByteIndex: upon receiving a mouseDown event, and then continueSelectionWithEvent:forByteIndex: for mouseDragged events, terminating with endSelectionWithEvent:forByteIndex: upon receiving the mouse up. HFController will compute the correct selected ranges and propagate any changes via the HFControllerPropertyBits mechanism.

(void) - beginSelectionWithEvent:forByteIndex:
 
(void) - continueSelectionWithEvent:forByteIndex:
 
(void) - endSelectionWithEvent:forByteIndex:
 
Scrollling

Support for the mouse wheel and scroll bars.

(void) - scrollWithScrollEvent:
 
(void) - scrollByLines:
 
Keyboard navigation

Support for chaging the selection via the keyboard

(void) - moveInDirection:byByteCount:withSelectionTransformation:usingAnchor:
 
(void) - moveInDirection:withGranularity:andModifySelection:
 
(void) - moveToLineBoundaryInDirection:andModifySelection:
 
Text editing

Methods to support common text editing operations

(BOOL) - insertByteArray:replacingPreviousBytes:allowUndoCoalescing:
 
(BOOL) - insertData:replacingPreviousBytes:allowUndoCoalescing:
 
(void) - deleteSelection
 
(void) - deleteDirection:
 
Reading data

Methods for reading data

(NSData *) - dataForRange:
 
(void) - copyBytes:range:
 
(HFByteRangeAttributeArray *) - byteRangeAttributeArray
 
(HFByteRangeAttributeArray *) - attributesForBytesInRange:
 
(HFRange- rangeForBookmark:
 
(void) - setRange:forBookmark:
 
(NSIndexSet *) - bookmarksInRange:
 
(unsigned long long) - contentsLength
 

Protected Attributes

 _hfflags
 

Properties

NSUInteger bytesPerColumn
 
NSFont * font
 
NSUndoManager * undoManager
 
BOOL editable
 
BOOL shouldAntialias
 
BOOL shouldColorBytes
 
BOOL shouldShowCallouts
 
BOOL shouldHideNullBytes
 
BOOL shouldLiveReload
 
Edit Mode

Determines what mode we're in, read-only, overwrite or insert.

HFEditMode editMode
 

Representer handling.

Methods for modifying the list of HFRepresenters attached to a controller. Attached representers receive the controllerDidChange: message when various properties of the controller change. A representer may only be attached to one controller at a time. Representers are retained by the controller.

NSArray * representers
 Gets the current array of representers attached to this controller. More...
 
(void) - addRepresenter:
 Adds a new representer to this controller. More...
 
(void) - removeRepresenter:
 Removes an existing representer from this controller. The representer must be present in the array of representers. More...
 

Byte array

Set and get the byte array.

HFByteArraybyteArray
 
(void) - replaceByteArray:
 

Selection handling

Methods for manipulating the current selected ranges. Hex Fiend supports discontiguous selection.

NSArray * selectedContentsRanges
 
(IBAction) - selectAll:
 
(unsigned long long) - minimumSelectionLocation
 
(unsigned long long) - maximumSelectionLocation
 
(HFByteArray *) - byteArrayForSelectedContentsRanges
 

Displayed line range

Methods for setting and getting the current range of displayed lines.

HFFPRange displayedLineRange
 
(void) - maximizeVisibilityOfContentsRange:
 
(void) - centerContentsRange:
 

File writing dependency handling

(BOOL) - clearUndoManagerDependenciesOnRanges:inFile:hint:
 
(BOOL) + prepareForChangeInFile:fromWritingByteArray:
 

Detailed Description

HFController acts as the controller layer in the MVC architecture of HexFiend. The HFController plays several significant central roles, including:

An HFController is the top point of ownership for a HexFiend object graph. It retains both its ByteArray (model) and its array of Representers (views).

You create an HFController via [[HFController alloc] init]. After that, give it an HFByteArray via setByteArray:, and some Representers via addRepresenter:. Then insert the Representers' views in a window, and you're done.

Method Documentation

§ addRepresenter:()

- (void) addRepresenter: (HFRepresenter *)  representer

§ removeRepresenter:()

- (void) removeRepresenter: (HFRepresenter *)  representer

§ beginPropertyChangeTransaction()

- (NSUInteger) beginPropertyChangeTransaction

Begins delaying property change transactions. Returns a token that should be passed to endPropertyChangeTransactions:.

§ endPropertyChangeTransaction:()

- (void) endPropertyChangeTransaction: (NSUInteger)  token

Pass a token returned from beginPropertyChangeTransaction to this method to pop the transaction off the stack and, if the stack is empty, to notify Representers of all collected changes. Tokens cannot be popped out of order - they are used strictly as a correctness check.

§ replaceByteArray:()

- (void) replaceByteArray: (HFByteArray *)  newArray

Replaces the entire byte array with a new one, preserving as much of the selection as possible. Unlike setByteArray:, this method is undoable, and intended to be used from representers that make a global change (such as Replace All).

§ totalLineCount()

- (unsigned long long) totalLineCount

Returns the number of lines on which the cursor may be placed. This is always at least 1, and is equivalent to (unsigned long long)(HFRoundUpToNextMultiple(contentsLength, bytesPerLine) / bytesPerLine)

§ bytesPerLine()

- (NSUInteger) bytesPerLine

Indicates the number of bytes per line, which is a global property among all the line-oriented representers.

§ lineHeight()

- (CGFloat) lineHeight

Returns the height of a line, in points. This is generally determined by the font. Representers that wish to align things to lines should use this.

§ pulseSelection()

- (void) pulseSelection

Begins selection pulsing (e.g. following a successful Find operation). Representers will receive callbacks indicating that HFControllerSelectionPulseAmount has changed.

§ selectionPulseAmount()

- (double) selectionPulseAmount

Return the amount that the "Find pulse indicator" should show. 0 means no pulse, 1 means maximum pulse. This is useful for Representers that support find and replace.

§ selectAll:()

- (IBAction) selectAll: (id)  sender

Selects the entire contents.

§ minimumSelectionLocation()

- (unsigned long long) minimumSelectionLocation

Returns the smallest value in the selected contents ranges, or the insertion location if the selection is empty.

§ maximumSelectionLocation()

- (unsigned long long) maximumSelectionLocation

Returns the largest HFMaxRange of the selected contents ranges, or the insertion location if the selection is empty.

§ byteArrayForSelectedContentsRanges()

- (HFByteArray *) byteArrayForSelectedContentsRanges

Convenience method for creating a byte array containing all of the selected bytes. If the selection has length 0, this returns an empty byte array.

§ maximizeVisibilityOfContentsRange:()

- (void) maximizeVisibilityOfContentsRange: (HFRange range

Modify the displayedLineRange so that as much of the given range as can fit is visible. If possible, moves by as little as possible so that the visible ranges before and afterward intersect with each other.

§ centerContentsRange:()

- (void) centerContentsRange: (HFRange range

Modify the displayedLineRange as to center the given contents range. If the range is near the bottom or top, this will center as close as possible. If contents range is too large to fit, it centers the top of the range. contentsRange may be empty.

§ representer:changedProperties:()

- (void) representer: (HFRepresenter *)  rep
changedProperties: (HFControllerPropertyBits properties 

Representer initiated property changes Called from a representer to indicate when some internal property of the representer has changed which requires that some properties be recalculated.

Callback for a representer-initiated change to some property. For example, if some property of a view changes that would cause the number of bytes per line to change, then the representer should call this method which will trigger the HFController to recompute the relevant properties.

§ beginSelectionWithEvent:forByteIndex:()

- (void) beginSelectionWithEvent: (NSEvent *)  event
forByteIndex: (unsigned long long)  byteIndex 

Begin a selection session, with a mouse down at the given byte index.

§ continueSelectionWithEvent:forByteIndex:()

- (void) continueSelectionWithEvent: (NSEvent *)  event
forByteIndex: (unsigned long long)  byteIndex 

Continue a selection session, whe the user drags over the given byte index.

§ endSelectionWithEvent:forByteIndex:()

- (void) endSelectionWithEvent: (NSEvent *)  event
forByteIndex: (unsigned long long)  byteIndex 

End a selection session, with a mouse up at the given byte index.

§ scrollWithScrollEvent:()

- (void) scrollWithScrollEvent: (NSEvent *)  scrollEvent

Trigger scrolling appropriate for the given scroll event.

§ scrollByLines:()

- (void) scrollByLines: (long double)  lines

Trigger scrolling by the given number of lines. If lines is positive, then the document is scrolled down; otherwise it is scrolled up.

§ moveInDirection:byByteCount:withSelectionTransformation:usingAnchor:()

- (void) moveInDirection: (HFControllerMovementDirection direction
byByteCount: (unsigned long long)  amountToMove
withSelectionTransformation: (HFControllerSelectionTransformation transformation
usingAnchor: (BOOL)  useAnchor 

General purpose navigation function. Modify the selection in the given direction by the given number of bytes. The selection is modifed according to the given transformation. If useAnchor is set, then anchored selection is used; otherwise any anchor is discarded.

This has a few limitations:

  • Only HFControllerDirectionLeft and HFControllerDirectionRight movement directions are supported.
  • Anchored selection is not supported for HFControllerShiftSelection (useAnchor must be NO)

§ moveInDirection:withGranularity:andModifySelection:()

- (void) moveInDirection: (HFControllerMovementDirection direction
withGranularity: (HFControllerMovementGranularity granularity
andModifySelection: (BOOL)  extendSelection 

Navigation designed for key events.

§ moveToLineBoundaryInDirection:andModifySelection:()

- (void) moveToLineBoundaryInDirection: (HFControllerMovementDirection direction
andModifySelection: (BOOL)  extendSelection 

§ insertByteArray:replacingPreviousBytes:allowUndoCoalescing:()

- (BOOL) insertByteArray: (HFByteArray *)  byteArray
replacingPreviousBytes: (unsigned long long)  previousByteCount
allowUndoCoalescing: (BOOL)  allowUndoCoalescing 

Replaces the selection with the given data. For something like a hex view representer, it takes two keypresses to create a whole byte; the way this is implemented, the first keypress goes into the data as a complete byte, and the second one (if any) replaces it. If previousByteCount > 0, then that many prior bytes are replaced, without breaking undo coalescing. For previousByteCount to be > 0, the following must be true: There is only one selected range, and it is of length 0, and its location >= previousByteCount

These functions return YES if they succeed, and NO if they fail. Currently they may fail only in overwrite mode, if you attempt to insert data that would require lengthening the byte array.

These methods are undoable.

§ insertData:replacingPreviousBytes:allowUndoCoalescing:()

- (BOOL) insertData: (NSData *)  data
replacingPreviousBytes: (unsigned long long)  previousByteCount
allowUndoCoalescing: (BOOL)  allowUndoCoalescing 

§ deleteSelection()

- (void) deleteSelection

Deletes the selection. This operation is undoable.

§ deleteDirection:()

- (void) deleteDirection: (HFControllerMovementDirection direction

If the selection is empty, deletes one byte in a given direction, which must be HFControllerDirectionLeft or HFControllerDirectionRight; if the selection is not empty, deletes the selection. Undoable.

§ dataForRange:()

- (NSData *) dataForRange: (HFRange range

Returns an NSData representing the given HFRange. The length of the HFRange must be of a size that can reasonably be fit in memory. This method may cache the result.

§ copyBytes:range:()

- (void) copyBytes: (unsigned char *)  bytes
range: (HFRange range 

Copies data within the given HFRange into an in-memory buffer. This is equivalent to [[controller byteArray] copyBytes:bytes range:range].

§ byteRangeAttributeArray()

- (HFByteRangeAttributeArray *) byteRangeAttributeArray

Convenience method that returns the attributes of the underlying byte array. You can message it directly to add and remove attributes. If you do so, be sure to call representer:changedProperties: with the HFControllerByteRangeAttributes bit

§ attributesForBytesInRange:()

- (HFByteRangeAttributeArray *) attributesForBytesInRange: (HFRange range

Returns the attributes for the given range. This is a union of the receiver's byteRangeAttributeArray properties and the properties returned by the byte array itself. range.length must be <= NSUIntegerMax.

§ rangeForBookmark:()

- (HFRange) rangeForBookmark: (NSInteger)  bookmark

Returns the range for the given bookmark. If there is no bookmark, returns {ULLONG_MAX, ULLONG_MAX}.

§ setRange:forBookmark:()

- (void) setRange: (HFRange range
forBookmark: (NSInteger)  bookmark 

Sets the range for the given bookmark. Pass {ULLONG_MAX, ULLONG_MAX} to remove the bookmark. Undoable.

§ bookmarksInRange:()

- (NSIndexSet *) bookmarksInRange: (HFRange range

Returns an NSIndexSet of the bookmarks in the given range.

§ contentsLength()

- (unsigned long long) contentsLength

Returns total number of bytes. This is equivalent to [[controller byteArray] length].

§ prepareForChangeInFile:fromWritingByteArray:()

+ (BOOL) prepareForChangeInFile: (NSURL *)  targetFile
fromWritingByteArray: (HFByteArray *)  array 

Attempts to clear all dependencies on the given file (clipboard, undo, etc.) that could not be preserved if the file were written. Returns YES if we successfully prepared, NO if someone objected. This works by posting a HFPrepareForChangeInFileNotification. HFController does not register for this notification: instead the owners of the HFController are expected to register for HFPrepareForChangeInFileNotification and react appropriately.

§ clearUndoManagerDependenciesOnRanges:inFile:hint:()

- (BOOL) clearUndoManagerDependenciesOnRanges: (NSArray *)  ranges
inFile: (HFFileReference *)  reference
hint: (NSMutableDictionary *)  hint 

Attempts to break undo stack dependencies for writing the given file. If it is unable to do so, it will clear the controller's contributions to the stack. Returns YES if it successfully broke the dependencies, and NO if the stack had to be cleared.

Member Data Documentation

§ _hfflags

- _hfflags
protected

Property Documentation

§ representers

- (NSArray*) representers
readatomiccopy

§ byteArray

- (HFByteArray*) byteArray
readwritenonatomicstrong

The byte array must be non-nil. In general, HFRepresenters should not use this to determine what bytes to display. Instead they should use copyBytes:range: or dataForRange: below.

§ selectedContentsRanges

- (NSArray*) selectedContentsRanges
readwritenonatomiccopy

An array of HFRangeWrappers, representing the selected ranges. It satisfies the following: The array is non-nil. There always is at least one selected range. If any range has length 0, that range is the only range. No range extends beyond the contentsLength, with the exception of a single zero-length range at the end.

When setting, the setter MUST obey the above criteria. A zero length range when setting or getting represents the cursor position.

§ bytesPerColumn

- (NSUInteger) bytesPerColumn
readwritenonatomicassign

§ editMode

- (HFEditMode) editMode
readwritenonatomicassign

§ displayedLineRange

- (HFFPRange) displayedLineRange
readwritenonatomicassign

Get the current displayed line range. The displayed line range is an HFFPRange (range of long doubles) containing the lines that are currently displayed.

The values may be fractional. That is, if only the bottom half of line 4 through the top two thirds of line 8 is shown, then the displayedLineRange.location will be 4.5 and the displayedLineRange.length will be 3.17 ( = 7.67 - 4.5). Representers are expected to be able to handle such fractional values.

When setting the displayed line range, the given range must be nonnegative, and the maximum of the range must be no larger than the total line count.

§ font

- (NSFont*) font
readwritenonatomiccopy

The current font.

§ undoManager

- (NSUndoManager*) undoManager
readwritenonatomicstrong

The undo manager. If no undo manager is set, then undo is not supported. By default the undo manager is nil.

§ editable

- (BOOL) editable
readwritenonatomicassign

Whether the user can edit the document.

§ shouldAntialias

- (BOOL) shouldAntialias
readwritenonatomicassign

Whether the text should be antialiased. Note that Mac OS X settings may prevent antialiasing text below a certain point size.

§ shouldColorBytes

- (BOOL) shouldColorBytes
readwritenonatomicassign

When enabled, characters have a background color that correlates to their byte values.

§ shouldShowCallouts

- (BOOL) shouldShowCallouts
readwritenonatomicassign

When enabled, byte bookmarks display callout-style labels attached to them.

§ shouldHideNullBytes

- (BOOL) shouldHideNullBytes
readwritenonatomicassign

When enabled, null bytes are hidden in the hex view.

§ shouldLiveReload

- (BOOL) shouldLiveReload
readwritenonatomicassign

When enabled, unmodified documents are auto refreshed to their latest on disk state.


The documentation for this class was generated from the following file: