riched20: comments - descriptions of functions in run.c
Krzysztof Foltman
wdev at foltman.com
Wed Aug 2 13:33:26 CDT 2006
ChangeLog:
* Added short descriptions to functions in run.c, just in case anybody
had any doubts about what they actually do
Have fun,
Krzysztof
-------------- next part --------------
diff --git a/dlls/riched20/run.c b/dlls/riched20/run.c
old mode 100644
new mode 100755
index f5ea660..a2c121a
--- a/dlls/riched20/run.c
+++ b/dlls/riched20/run.c
@@ -27,6 +27,11 @@ WINE_DEFAULT_DEBUG_CHANNEL(richedit);
WINE_DECLARE_DEBUG_CHANNEL(richedit_check);
WINE_DECLARE_DEBUG_CHANNEL(richedit_lists);
+/******************************************************************************
+ * ME_CanJoinRuns
+ *
+ * Returns 1 if two runs can be safely merged into one, 0 otherwise.
+ */
int ME_CanJoinRuns(ME_Run *run1, ME_Run *run2)
{
if ((run1->nFlags | run2->nFlags) & MERF_NOJOIN)
@@ -45,8 +50,18 @@ void ME_SkipAndPropagateCharOffset(ME_Di
ME_PropagateCharOffset(p, shift);
}
+/******************************************************************************
+ * ME_PropagateCharOffsets
+ *
+ * Shifts (increases or decreases) character offset (relative to beginning of
+ * the document) of the part of the text starting from given place.
+ */
void ME_PropagateCharOffset(ME_DisplayItem *p, int shift)
{
+ /* Runs in one paragraph contain character offset relative to their owning
+ * paragraph. If we start the shifting from the run, we need to shift
+ * all the relative offsets until the end of the paragraph
+ */
if (p->type == diRun) /* propagate in all runs in this para */
{
TRACE("PropagateCharOffset(%s, %d)\n", debugstr_w(p->member.run.strText->szData), shift);
@@ -56,6 +71,10 @@ void ME_PropagateCharOffset(ME_DisplayIt
p = ME_FindItemFwd(p, diRunOrParagraphOrEnd);
} while(p->type == diRun);
}
+ /* Runs in next paragraphs don't need their offsets updated, because they,
+ * again, those offsets are relative to their respective paragraphs.
+ * Instead of that, we're updating paragraphs' character offsets.
+ */
if (p->type == diParagraph) /* propagate in all next paras */
{
do {
@@ -64,6 +83,9 @@ void ME_PropagateCharOffset(ME_DisplayIt
p = p->member.para.next_para;
} while(p->type == diParagraph);
}
+ /* diTextEnd also has character offset in it, which makes finding text length
+ * easier. But it needs to be up to date first.
+ */
if (p->type == diTextEnd)
{
p->member.para.nCharOfs += shift;
@@ -71,6 +93,11 @@ void ME_PropagateCharOffset(ME_DisplayIt
}
}
+/******************************************************************************
+ * ME_CheckCharOffsets
+ *
+ * Checks if editor lists' validity and optionally dumps the document structure
+ */
void ME_CheckCharOffsets(ME_TextEditor *editor)
{
ME_DisplayItem *p = editor->pBuffer->pFirst;
@@ -111,6 +138,13 @@ void ME_CheckCharOffsets(ME_TextEditor *
} while(1);
}
+/******************************************************************************
+ * ME_CharOfsFromRunOfs
+ *
+ * Converts a character position relative to the start of the run, to a
+ * character position relative to the start of the document.
+ * Kind of a "local to global" offset conversion.
+ */
int ME_CharOfsFromRunOfs(ME_TextEditor *editor, ME_DisplayItem *pRun, int nOfs)
{
ME_DisplayItem *pPara;
@@ -125,11 +159,25 @@ int ME_CharOfsFromRunOfs(ME_TextEditor *
+ ME_VPosToPos(pRun->member.run.strText, nOfs);
}
+/******************************************************************************
+ * ME_CursorFromCharOfs
+ *
+ * Converts a character offset (relative to the start of the document) to
+ * a cursor structure (which contains a run and a position relative to that
+ * run).
+ */
void ME_CursorFromCharOfs(ME_TextEditor *editor, int nCharOfs, ME_Cursor *pCursor)
{
ME_RunOfsFromCharOfs(editor, nCharOfs, &pCursor->pRun, &pCursor->nOffset);
}
+/******************************************************************************
+ * ME_RunOfsFromCharOfs
+ *
+ * Find a run and relative character offset given an absolute character offset
+ * (absolute offset being an offset relative to the start of the document).
+ * Kind of a "global to local" offset conversion.
+ */
void ME_RunOfsFromCharOfs(ME_TextEditor *editor, int nCharOfs, ME_DisplayItem **ppRun, int *pOfs)
{
ME_DisplayItem *pPara;
@@ -176,6 +224,11 @@ void ME_RunOfsFromCharOfs(ME_TextEditor
assert((*ppRun)->member.run.nFlags & MERF_ENDPARA);
}
+/******************************************************************************
+ * ME_JoinRuns
+ *
+ * Merges two adjacent runs, the one given as a parameter and the next one.
+ */
void ME_JoinRuns(ME_TextEditor *editor, ME_DisplayItem *p)
{
ME_DisplayItem *pNext = p->next;
@@ -184,8 +237,11 @@ void ME_JoinRuns(ME_TextEditor *editor,
assert(p->member.run.nCharOfs != -1);
ME_GetParagraph(p)->member.para.nFlags |= MEPF_REWRAP;
- if (editor->bCaretAtEnd && editor->pCursors[0].pRun == pNext)
+ /* if we were at the end of screen line, and the next run is in the new
+ * line, then it's not the end of the line anymore */
+ if (editor->bCaretAtEnd && editor->pCursors[0].pRun == pNext)
editor->bCaretAtEnd = FALSE;
+ /* Update all cursors so that they don't contain the soon deleted run */
for (i=0; i<editor->nCursors; i++) {
if (editor->pCursors[i].pRun == pNext) {
editor->pCursors[i].pRun = p;
@@ -205,6 +261,12 @@ void ME_JoinRuns(ME_TextEditor *editor,
}
}
+/******************************************************************************
+ * ME_SplitRun
+ *
+ * Splits a run into two in a given place. It also updates the screen position
+ * and size (extent) of the newly generated runs.
+ */
ME_DisplayItem *ME_SplitRun(ME_Context *c, ME_DisplayItem *item, int nVChar)
{
ME_TextEditor *editor = c->editor;
@@ -248,7 +310,12 @@ ME_DisplayItem *ME_SplitRun(ME_Context *
return item2;
}
-/* split a run starting from voffset */
+/******************************************************************************
+ * ME_SplitRunSimple
+ *
+ * Does the most basic job of splitting a run into two - it does not
+ * update the positions and extents.
+ */
ME_DisplayItem *ME_SplitRunSimple(ME_TextEditor *editor, ME_DisplayItem *item, int nVChar)
{
ME_Run *run = &item->member.run;
@@ -283,6 +350,11 @@ ME_DisplayItem *ME_SplitRunSimple(ME_Tex
return item2;
}
+/******************************************************************************
+ * ME_MakeRun
+ *
+ * A helper function to create run structures quickly.
+ */
ME_DisplayItem *ME_MakeRun(ME_Style *s, ME_String *strData, int nFlags)
{
ME_DisplayItem *item = ME_MakeDI(diRun);
@@ -294,7 +366,11 @@ ME_DisplayItem *ME_MakeRun(ME_Style *s,
return item;
}
-
+/******************************************************************************
+ * ME_InsertRun
+ *
+ * Inserts a run at a given character position (offset).
+ */
ME_DisplayItem *ME_InsertRun(ME_TextEditor *editor, int nCharOfs, ME_DisplayItem *pItem)
{
ME_Cursor tmp;
@@ -311,6 +387,13 @@ ME_DisplayItem *ME_InsertRun(ME_TextEdit
return pDI;
}
+/******************************************************************************
+ * ME_InsertRunAtCursor
+ *
+ * Inserts a new run with given style, flags and content at a given position,
+ * which is passed as a cursor structure (which consists of a run and
+ * a run-relative character offset).
+ */
ME_DisplayItem *
ME_InsertRunAtCursor(ME_TextEditor *editor, ME_Cursor *cursor, ME_Style *style,
const WCHAR *str, int len, int flags)
@@ -319,6 +402,8 @@ ME_InsertRunAtCursor(ME_TextEditor *edit
ME_UndoItem *pUI;
if (cursor->nOffset) {
+ /* We're inserting at the middle of the existing run, which means that
+ * that run must be split. It isn't always necessary, but */
cursor->pRun = ME_SplitRunSimple(editor, cursor->pRun, cursor->nOffset);
cursor->nOffset = 0;
}
@@ -339,6 +424,13 @@ ME_InsertRunAtCursor(ME_TextEditor *edit
return pDI;
}
+/******************************************************************************
+ * ME_UpdateRunFlags
+ *
+ * Determine some of run attributes given its content (style, text content).
+ * Some flags cannot be determined by this function (MERF_GRAPHICS,
+ * MERF_ENDPARA)
+ */
void ME_UpdateRunFlags(ME_TextEditor *editor, ME_Run *run)
{
assert(run->nCharOfs != -1);
@@ -375,6 +467,12 @@ void ME_UpdateRunFlags(ME_TextEditor *ed
run->nFlags &= ~(MERF_WHITESPACE | MERF_STARTWHITE | MERF_ENDWHITE);
}
+/******************************************************************************
+ * ME_GetGraphicsSize
+ *
+ * Sets run extent for graphics runs. This functionality is just a placeholder
+ * for future OLE object support, and will be removed.
+ */
void ME_GetGraphicsSize(ME_TextEditor *editor, ME_Run *run, SIZE *pSize)
{
assert(run->nFlags & MERF_GRAPHICS);
@@ -382,6 +480,13 @@ void ME_GetGraphicsSize(ME_TextEditor *e
pSize->cy = 64;
}
+/******************************************************************************
+ * ME_CharFromPoint
+ *
+ * Returns a character position inside the run given a run-relative
+ * pixel horizontal position. This version rounds left (ie. if the second
+ * character is at pixel position 8, then for cx=0..7 it returns 0).
+ */
int ME_CharFromPoint(ME_TextEditor *editor, int cx, ME_Run *run)
{
int fit = 0;
@@ -393,7 +498,7 @@ int ME_CharFromPoint(ME_TextEditor *edit
if (run->nFlags & (MERF_TAB | MERF_CELL))
{
- if (cx < run->nWidth/2)
+ if (cx < run->nWidth/2)
return 0;
return 1;
}
@@ -414,6 +519,17 @@ int ME_CharFromPoint(ME_TextEditor *edit
return fit;
}
+/******************************************************************************
+ * ME_CharFromPointCursor
+ *
+ * Returns a character position inside the run given a run-relative
+ * pixel horizontal position. This version rounds to the nearest character edge
+ * (ie. if the second character is at pixel position 8, then for cx=0..3
+ * it returns 0, and for cx=4..7 it returns 1).
+ *
+ * It is used for mouse click handling, for better usability (and compatibility
+ * with the native control).
+ */
int ME_CharFromPointCursor(ME_TextEditor *editor, int cx, ME_Run *run)
{
int fit = 0, fit1 = 0;
@@ -457,6 +573,12 @@ int ME_CharFromPointCursor(ME_TextEditor
return fit;
}
+/******************************************************************************
+ * ME_PointFromChar
+ *
+ * Returns a run-relative pixel position given a run-relative character
+ * position (character offset)
+ */
int ME_PointFromChar(ME_TextEditor *editor, ME_Run *pRun, int nOffset)
{
SIZE size;
@@ -476,6 +598,11 @@ int ME_PointFromChar(ME_TextEditor *edit
return size.cx;
}
+/******************************************************************************
+ * ME_GetTextExtent
+ *
+ * Finds a width and a height of the text using a specified style
+ */
void ME_GetTextExtent(ME_Context *c, LPCWSTR szText, int nChars, ME_Style *s,
SIZE *size)
{
@@ -486,6 +613,12 @@ void ME_GetTextExtent(ME_Context *c, LPC
ME_UnselectStyleFont(c->editor, hDC, s, hOldFont);
}
+/******************************************************************************
+ * ME_GetRunSizeCommon
+ *
+ * Finds width, height, ascent and descent of a run, up to given character
+ * (nLen).
+ */
SIZE ME_GetRunSizeCommon(ME_Context *c, ME_Paragraph *para, ME_Run *run, int nLen, int *pAscent, int *pDescent)
{
SIZE size;
@@ -545,12 +678,25 @@ SIZE ME_GetRunSizeCommon(ME_Context *c,
return size;
}
+/******************************************************************************
+ * ME_GetRunSize
+ *
+ * Finds width and height (but not ascent and descent) of a part of the run
+ * up to given character.
+ */
SIZE ME_GetRunSize(ME_Context *c, ME_Paragraph *para, ME_Run *run, int nLen)
{
int asc, desc;
return ME_GetRunSizeCommon(c, para, run, nLen, &asc, &desc);
}
+/******************************************************************************
+ * ME_CalcRunExtent
+ *
+ * Updates the size of the run (fills width, ascent and descent). The height
+ * is calculated based on whole row's ascent and descent anyway, so no need
+ * to use it here.
+ */
void ME_CalcRunExtent(ME_Context *c, ME_Paragraph *para, ME_Run *run)
{
if (run->nFlags & MERF_HIDDEN)
@@ -565,12 +711,24 @@ void ME_CalcRunExtent(ME_Context *c, ME_
}
}
+/******************************************************************************
+ * ME_MustBeWrapped
+ *
+ * This should ensure that the given paragraph is wrapped so that its screen
+ * row structure may be used. But it doesn't, yet.
+ */
void ME_MustBeWrapped(ME_Context *c, ME_DisplayItem *para)
{
assert(para->type == diParagraph);
/* FIXME */
}
+/******************************************************************************
+ * ME_SetSelectionCharFormat
+ *
+ * Applies a style change, either to a current selection, or to insert cursor
+ * (ie. the style next typed characters will use).
+ */
void ME_SetSelectionCharFormat(ME_TextEditor *editor, CHARFORMAT2W *pFmt)
{
int nFrom, nTo;
@@ -588,6 +746,11 @@ void ME_SetSelectionCharFormat(ME_TextEd
ME_SetCharFormat(editor, nFrom, nTo-nFrom, pFmt);
}
+/******************************************************************************
+ * ME_SetCharFormat
+ *
+ * Applies a style change to the specified part of the text
+ */
void ME_SetCharFormat(ME_TextEditor *editor, int nOfs, int nChars, CHARFORMAT2W *pFmt)
{
ME_Cursor tmp, tmp2;
@@ -632,6 +795,11 @@ void ME_SetCharFormat(ME_TextEditor *edi
}
}
+/******************************************************************************
+ * ME_SetDefaultCharFormat
+ *
+ * Applies a style change to the default character style.
+ */
void ME_SetDefaultCharFormat(ME_TextEditor *editor, CHARFORMAT2W *mod)
{
ME_Style *style;
@@ -658,6 +826,12 @@ void ME_GetRunCharFormat(ME_TextEditor *
ME_CopyCharFormat(pFmt, &run->member.run.style->fmt);
}
+/******************************************************************************
+ * ME_GetDefaultCharFormat
+ *
+ * Retrieves the current default character style (the one applied where no
+ * other style was applied) .
+ */
void ME_GetDefaultCharFormat(ME_TextEditor *editor, CHARFORMAT2W *pFmt)
{
int nFrom, nTo;
@@ -665,6 +839,12 @@ void ME_GetDefaultCharFormat(ME_TextEdit
ME_CopyCharFormat(pFmt, &editor->pBuffer->pDefaultStyle->fmt);
}
+/******************************************************************************
+ * ME_GetSelectionCharFormat
+ *
+ * If selection exists, it returns all style elements that are set consistently
+ * in the whole selection. If not, it just returns the current style.
+ */
void ME_GetSelectionCharFormat(ME_TextEditor *editor, CHARFORMAT2W *pFmt)
{
int nFrom, nTo;
@@ -677,6 +857,12 @@ void ME_GetSelectionCharFormat(ME_TextEd
ME_GetCharFormat(editor, nFrom, nTo, pFmt);
}
+/******************************************************************************
+ * ME_GetCharFormat
+ *
+ * Returns the style consisting of those attributes which are consistently set
+ * in the whole character range.
+ */
void ME_GetCharFormat(ME_TextEditor *editor, int nFrom, int nTo, CHARFORMAT2W *pFmt)
{
ME_DisplayItem *run, *run_end;
More information about the wine-patches
mailing list